Request For Comments (RFCs)
  • Request for comments (RFC)
  • RFC 001: Matcher architecture
  • RFC 002: Archival Storage Service
  • RFC 003: Asset Access
  • RFC 004: METS Adapter
  • RFC 005: Reporting Pipeline
  • RFC 006: Reindexer architecture
  • RFC 007: Goobi Upload
  • RFC 008: API Filtering
  • RFC 009: AWS account setup
  • RFC 010: Data model
  • RFC 011: Network Architecture
  • RFC 012: API Architecture
  • RFC 013: Release & Deployment tracking
    • Deployment example
    • Version 1
  • RFC 014: Born digital workflow
  • RFC 015: How we work
    • Code Reviews
    • Shared Libraries
  • RFC 016: Holdings service
  • RFC 017: URL Design
  • RFC 018: Pipeline Tracing
  • RFC 019: Platform Reliability
    • CI/CD
    • Observability
    • Reliability
  • RFC 020: Locations and requesting
  • RFC 021: Data science in the pipeline
  • RFC 022: Logging
    • Logging example
  • RFC 023: Images endpoint
  • RFC 024: Library management
  • RFC 025: Tagging our Terraform resources
  • RFC 026: Relevance reporting service
  • RFC 026: Relation Embedder
  • RFC 027: Pipeline Intermediate Storage
  • RFC 029: Work state modelling
  • RFC 030: Pipeline merging
  • RFC 031: Relation Batcher
  • RFC 032: Calm deletion watcher
  • RFC 033: Api internal model versioning
  • RFC 034: Modelling Locations in the Catalogue API
  • RFC 035: Modelling MARC 856 "web linking entry"
  • RFC 036: Modelling holdings records
  • RFC 037: API faceting principles & expectations
  • RFC 038: Matcher versioning
  • RFC 039: Requesting API design
  • RFC 040: TEI Adapter
  • RFC 041: Tracking changes to the Miro data
  • RFC 042: Requesting model
  • RFC 043: Removing deleted records from (re)indexes
  • RFC 044: Tracking Patron Deletions
  • RFC 045: Work relationships in Sierra, part 2
    • Work relationships in Sierra
  • RFC 046: Born Digital in IIIF
  • RFC 047: Changing the structure of the Catalogue API index
  • RFC 048: Concepts work plan
  • RFC 049: Changing how aggregations are retrieved by the Catalogue API
  • RFC 050: Design considerations for the concepts API
  • 051-concepts-adapters
  • RFC 052: The Concepts Pipeline - phase one
  • RFC 053: Logging in Lambdas
  • RFC 054: Authoritative ids with multiple Canonical ids.
  • RFC 055: Genres as Concepts
  • RFC 056: Prismic to Elasticsearch ETL pipeline
  • RFC 058: Relevance testing
    • Examples of rank CLI usage
  • RFC 059: Splitting the catalogue pipeline Terraform
  • RFC 060: Service health-check principles
  • RFC 061: Content API next steps
  • RFC 062: Content API: All search and indexing of addressable content types
  • RFC 062: Wellcome Collection Graph overview and next steps
  • RFC 063: Catalogue Pipeline services from ECS to Lambda
  • RFC 064: Graph data model
  • RFC 065: Library Data Link Explorer
  • RFC 066: Catalogue Graph pipeline
  • RFC 067: Prismic API ID casing
  • RFC 068: Exhibitions in Content API
  • RFC 069: Catalogue Graph Ingestor
  • RFC 070: Concepts API changes
  • RFC 071: Python Building and Deployment
    • The current state
  • RFC 072: Transitive Sierra hierarchies
  • RFC 073: Content API
    • Content API: articles endpoint
    • Content API: Events endpoint
    • Content API: exhibitions endpoint
    • The future of this endpoint
  • RFC 074: Offsite requesting
    • Sierra locations in the Catalogue API
Powered by GitBook
On this page
  • Context
  • Custom type API IDs
  • Field API IDs
  • Slice IDs
  • New vs. legacy
  • Proposal

RFC 067: Prismic API ID casing

This RFC proposes a consistent casing for Prismic API IDs across custom types, fields, and slices, to align with Prismic defaults and improve maintainability.

Last modified: 2025-01-13T12:28:03+00:00

Context

We run a spike to assess time/effort/risk to do the following:

  • Use kebab-case for Custom type API IDs (plural/singular for reusable/single respectively) – this has to be overridden in SliceMachine. Or possibly convert all of these to snake_case (which wouldn't need to be overridden in SliceMachine) for consistency with Slice API IDs

  • Use camelCase for all (Custom type and Slice) field API IDs – this has to be overridden in SliceMachine

  • Use snake_case for Slice API IDs – this is SliceMachine default

We’d like to make sure our Prismic API IDs are written with consistent casing and that we’re following defaults from Prismic so that we’re going with the grain as far as possible and not having to manually override auto-generated SliceMachine files.

Custom type API IDs

When we started using Prismic we decided that these should be kebab-cased. Also, if the type was ‘reusable’ it should be plural, if it was 'single' it should be singular. For example, the reusable 'Exhibition highlight tour' type has an API ID of exhibition-highlight-tours whereas the single 'Global alert' type has an API ID of global-alert.

SliceMachine makes these snake_case by default but allows this to be overridden easily in the Graphical User Interface (GUI) and to-date we have made all of them kebab-case, so there probably isn't a good case for changing these to snake_case now.

A couple of reusable content types have been given singular API IDs – card and collection-venue – should we consider changing these two to cards and collection-venues?

Field API IDs

Field API IDs are individual properties on a Custom type or Slice. More often than not these are individual words (e.g. title), which keeps things simple. When there's more than one word, we now have a mixture of snake_case and camelCase field API IDs.

SliceMachine defaults to snake_case (based on the label), although this is readily overridable in the GUI at the point of adding the field.

We exclusively work with camelCased variables in TypeScript and while snake_cased object properties aren’t a problem (e.g. data.some_property), we wouldn’t be able to destructure those properties off the data object without it being a linting error:

const { some_property } = data; // <-- linting error

Whereas this isn’t a problem:

const { someProperty } = data; // <-- ✨

So perhaps the preference should be for updating the field names at point of creation to be camelCased to remove the need for an extra renaming variable step in the TypeScript.

Slice IDs

New vs. legacy

Whatever pattern we decide to go with in future, we also need to decide whether we should apply it to legacy content. Doing it for all content old and new would obviously be good for consistency but needs to be weighed against the effort required and risks associated with migrating the content.

Proposal

We do a spike to establish the effort and risk around renaming various API IDs and decide what to do next based on the outcomes.

PreviousRFC 066: Catalogue Graph pipelineNextRFC 068: Exhibitions in Content API

Last updated 2 days ago

Prior to our use of SliceMachine, we gave our Slices camelCased IDs. However, SliceMachine requires that Slices have snake_cased IDs (it doesn’t let you override it in the GUI). When we migrated to SliceMachine we updated the Slice IDs in the and files that it generates to be camelCased in order to be able to use our existing code consistently. But each subsequent change to the Slice through SliceMachine will revert the IDs to snake_case and we have to remember to override it back to camelCase in several places across these two files. For newer Slices we have kept the default (snake_case) ids rather than override them to camelCase.

I don’t think we deal directly with the Slice IDs. Instead, we send all of them (in ) along to SliceMachine, so the linting problems mentioned above don’t arise. As such, I propose that we move to using snake_case for all Slice IDs.

Example of a camelCase field
Example of a snake_case field
code
type
a components object