The attribute vocabulary

An attribute is one value a component accepts. This page is the vocabulary: what an attribute declares, what a value may be, and which of it a consumer is expected to read.

It is a contract between three packages — a language adapter emits these shapes by reading a component's source, the CMS validates, stores and signs them, and a client SDK reads them to render. That is why it is defined once, in @genoacms/internal, rather than in any one of them.

An attribute is a meta-schema

interface Attribute {
  uid: string        // stable identity, preserved across re-analysis
  name: string       // derived from the component's parameter name
  type: AttributeType
  schema: MetaSchema // everything about the value, in JSON Schema terms
}
ts

Everything about the value lives inside schema, and nothing beside it. Earlier revisions carried flat siblings — a maxLength next to schema.maxLength, a maxComponents next to maxItems — which is two places for one fact.

Inside a signed payload, two places for one fact is a correctness hazard

The two can disagree, and the signature attests to both. There is then no way to say which one the publisher meant.

An unset constraint is an absent key

Optional constraints are omitted when unset — never null, never undefined, never an empty value.

Payloads are signed over their RFC 8785 canonical form, and {"minimum":null} and {} canonicalize to different bytes. Two producers disagreeing about which to write make the same component sign two ways, and neither signature is wrong.

The types

typeValue in a page's dataSchema
booleanbooleanBooleanMetaSchema
numbernumberNumberMetaSchema
stringstringStringMetaSchema
textstringStringMetaSchema
markdownstringStringMetaSchema
richTextstringStringMetaSchema
linkstring[]LinksMetaSchema
storageResourcestring[]StorageResourcesMetaSchema
componentsReadablePageNode[]ComponentsAttributeMetaSchema

string, text, markdown and richText share one schema and differ in how the CMS edits them — a single line, a textarea, a markdown editor, a rich-text editor. To a consumer all four arrive as a string, and what differs is what is inside it.

Every schema carries title, description and required.

title is the name a page's data is keyed by

This is the field that matters most to a consumer, and it is easy to miss.

node.data[publication.attributes[uid].schema.title]
js

Not attribute.name, which is the component's parameter name. attributeNames(publication) resolves this for you, in parameter order, and resolvePage goes further and hands back the values themselves already ordered.

Numbers

interface NumberMetaSchema {
  type: 'number'
  title: string
  description: string
  minimum?: number
  maximum?: number
  multipleOf?: number
  decimalPlaces?: number
  required: boolean
  default?: number
}
ts

decimalPlaces is a non-standard keyword, kept deliberately. It is not a duplicate of multipleOf: that constrains the value, while this is display precision. A component may accept any real number and still wish to render two decimals, so a step of 0.01 and a precision of 2 are different statements that can legitimately disagree. Deriving one from the other would silently change rendering for any component that set a step without a precision.

JSON Schema permits unknown keywords and JCS canonicalizes any JSON, so nothing downstream is harmed.

Strings

interface StringMetaSchema {
  type: 'string'
  title: string
  description: string
  minLength?: number
  maxLength?: number
  pattern?: string
  format?: string
  required: boolean
  default?: string
}
ts

Links

A link is either external or internal, and the discriminant is explicit:

type LinkAttributeValue =
  | { isExternal: true, url: string }
  | { isExternal: false, pageName: string }
ts

Stated rather than inferred from which field is present, so a link with neither is malformed rather than quietly external.

Storage resources

interface StorageResourceValue {
  bucket: string
  name: string
}
ts

Declared structurally rather than imported from @genoacms/contracts, which depends on this package — importing back would be a cycle.

Components

A slot. The value in a page's data is an array of nested page nodes, each with its own pin, and the SDK resolves them depth first: a parent is handed its slot already rendered.

interface ComponentsAttributeMetaSchema {
  type: 'array'
  title: string
  description: string
  items: { type: 'string', enum?: string[] }
  default?: string[]
  minItems?: number
  maxItems?: number
  required: boolean
}
ts

items.enum, when present, is the set of component names this slot accepts.

What a consumer is expected to read, and what it is not

A consumer reads each attribute's name — and, if it wants to describe the component in its own interface, title and description.

It is not expected to re-check constraints. minLength, maximum, pattern and the rest are the CMS's validation vocabulary, enforced when a value is authored. A renderer receives values that have already been resolved, and re-checking a constraint the CMS enforced would be a second opinion nobody asked for — one that would reject a page for a rule that changed after it was published.

The SDK reflects this: readPublication reads attributes only far enough to find their names, and passes over everything else.

Attributes and renaming

uid is what survives a rename: re-analysing a component keeps the uid, so pages that already store values under the old arrangement keep working.

The name is what a page's data is keyed by, which is why the CMS refuses to register two attributes with the same name. attributeNames enforces the same rule at read time and refuses a publication with a duplicate name, an attribute with no name, or an attributeOrder entry naming an attribute that is not described.