CEDAR Template Model Specification

This specification defines the structural model for the CEDAR Template Model and its concrete JSON wire form.

It separates schema definition, presentation structure, reusable artifacts, contextual embedding, and instance data, and is layered as an abstract grammar paired with a JSON wire grammar, encoding rules, host-language bindings, and a normative validation algorithm.

The core concepts are Artifact, SchemaArtifact, Template, Field, PresentationComponent, EmbeddedArtifact, TemplateInstance, and InstanceValue. Every concrete artifact carries a top-level ModelVersion identifying the version of the CEDAR structural model it conforms to.

Scope

This specification defines:

• the core metamodel and abstract grammar
• artifact metadata, identity, lifecycle, and versioning
• the field-spec system (twenty concrete field families)
• the presentation-component model
• the instance model
• the JSON wire form (encoding rules, kind discriminator, wrapper collapse, property-name map)
• encoding and decoding semantics, including a normative error model
• a canonical validation algorithm with explicit error reports
• host-language binding idioms for TypeScript, Java, and Python
• a derived RDF projection of Value instances
• a cross-language conformance test suite

Document Structure

• notation.md — notation conventions used throughout the specification.
• metamodel.md — conceptual overview: principal categories, the field hierarchy, the layered specification, and cross-cutting conventions.
• grammar.md — the abstract EBNF-style grammar, including the FieldSpec system, defaults, primitive lexical-form productions, and related constraints.
• wire-grammar.md — the JSON wire grammar: kind rule, wrapper collapse, encoding rules, and the property-name map for every production.
• serialization.md — encoding and decoding semantics: round-tripping, the wrapping principle, the error model, and worked examples.
• bindings.md — host-language idioms (TypeScript, Java, Python) and codebase-organisation guidance.
• validation.md — the canonical validation algorithm, with per-step error reports.
• presentation.md — the PresentationComponent family.
• instances.md — TemplateInstance and InstanceValue semantics, including the explicit “defaults are not part of instances” rule.
• rdf-projection.md — the derived projection from CEDAR Value instances to RDF.
• index-of-productions.md — auto-generated A–Z index of every production in the specification.

A cross-language conformance test suite accompanies the specification: 114 fixtures (91 valid round-trip cases, 23 invalid cases with expected-error reports) embedded into serialization.md §8 and intended as a binding-acceptance contract.

Core Design Principles

• Schema definition MUST be separated from instance data.
• Semantic structure MUST be separated from presentation.
• Templates MUST contain embedded artifacts rather than directly containing Field, Template, or PresentationComponent.
• PresentationComponent MUST NOT contribute instance values.
• Defaults are UI/UX initialisation only and never appear in TemplateInstance artifacts or in the RDF projection.
• Terminology MUST remain stable across this specification.

Open Questions

• Should the model support template-local (on-the-fly) fields without identity or versioning? See issue #1.
• Are the Name, Description, PreferredLabel, and AlternativeLabel properties on ArtifactMetadata all pulling their weight, or is there redundancy worth simplifying? See issue #2.
• Should instance structures eventually allow path-based keys in addition to EmbeddedArtifactKey?
• Should option sets for some FieldSpec variants become reusable artifacts?

Notation

This specification uses the terminology and naming conventions that are shared across the rest of the specification.

The production notation for the abstract grammar is defined in spec/grammar.md.

Conformance Language

The words MUST, MUST NOT, SHOULD, and MAY are used to express normative requirements when appropriate.

Naming Conventions

Defined terms use the terminology in this specification exactly. In particular, the following terms are normative and stable.

Schema and artifact terms:

• Artifact
• SchemaArtifact
• Template
• Field
• PresentationComponent

Embedding terms:

• EmbeddedArtifact
• EmbeddedField
• EmbeddedTemplate
• EmbeddedPresentationComponent
• EmbeddedArtifactKey

Instance terms:

• TemplateInstance
• InstanceValue
• FieldValue
• NestedTemplateInstance

Typing terms:

• FieldSpec

Value Notation

Value denotes an instance-level data value in the grammar.

Each Value family carries its content directly: a LexicalForm, an optional LanguageTag, an explicit datatype IRI (where one is configurable), or a boolean payload, depending on the family. There is no separate RDF-Literal layer in the abstract grammar; an RDF projection is defined separately in rdf-projection.md.

The normative structure and semantics of values are defined in the Values section of grammar.md.

Metamodel

Overview

This section provides a conceptual overview of the CEDAR Template Model. Its purpose is to describe the principal categories of constructs, the relationships among them, and the design rationale behind key decisions. It is intended as a companion to the formal abstract grammar defined in spec/grammar.md, which is the normative specification. Readers seeking precise structural definitions, production rules, or normative constraints should consult grammar.md directly.

The CEDAR Template Model is organised around three principal concerns: reusable schema artifacts that define structure, embedding constructs that contextualise those artifacts within a specific template, and template instances that record data conforming to a template.

Principal Categories

Artifact is the broadest category in the model. Every artifact carries a repository-assigned identifier, descriptive metadata, lifecycle metadata, and zero or more annotations. SchemaArtifact, PresentationComponent, and TemplateInstance are the three principal subclasses.

A SchemaArtifact is a reusable artifact that defines schema structure. Template and Field are the two concrete schema artifact kinds. Both carry versioning metadata — semantic version, publication status, optional lineage references — in addition to the common artifact metadata; see grammar.md for the normative shape. Independently of schema versioning, every concrete Artifact (every Template, every TemplateInstance, every Field, and every PresentationComponent) carries a top-level ModelVersion identifying the version of the CEDAR structural model the artifact conforms to.

A Template is the central container of the model. It specifies an ordered arrangement of EmbeddedArtifact constructs and defines the schema that TemplateInstance constructs must conform to.

A Field is an abstract category refined into a fixed set of typed concrete variants. Each concrete field carries a matching FieldSpec that specifies its value semantics and configuration: the field artifact carries identity, metadata, and lifecycle information, while the FieldSpec carries value rules and rendering properties. The full set of concrete variants, their groupings under abstract sub-categories (NumericField, TemporalField, EnumField, ContactField, ExternalAuthorityField), and the rationale behind the splits are documented in grammar.md and indexed in the Field Families chapter.

A PresentationComponent is a reusable non-data-bearing artifact that contributes presentational or instructional structure within a template. Examples include rich text, images, YouTube videos, section breaks, and page breaks. Presentation components do not produce instance values.

An EmbeddedArtifact contextualises a reusable artifact within a specific Template. There are three forms, and they carry different subsets of template-local properties:

• EmbeddedField carries the full property set: an EmbeddedArtifactKey, a typed reference to the embedded Field, and optional ValueRequirement, Cardinality, Visibility, family-typed defaultValue, LabelOverride, and Property (a semantic property IRI for the embedding site).
• EmbeddedTemplate carries the embedding key, the embedded template’s identifier, and optional ValueRequirement, Cardinality, Visibility, LabelOverride, and Property. It carries no defaultValue (templates do not have value-typed defaults).
• EmbeddedPresentationComponent carries only the embedding key, the embedded presentation component’s identifier, and an optional Visibility. It contributes no instance data and exists purely to contribute presentational structure.

An EmbeddedArtifactKey is the local identifier of an EmbeddedArtifact within its containing Template. It is the mechanism that connects template structure to instance structure.

A TemplateInstance is an artifact that records data conforming to a Template. It contains FieldValue and NestedTemplateInstance constructs keyed by EmbeddedArtifactKey, corresponding to the data-bearing embedded artifacts of the referenced template.

The diagram below sketches how the principal categories connect at runtime. Schema-side classes (definitions) are on the right; instance-side classes (data records) are on the left. The horizontal arrows show the two cross-side links: a TemplateInstance is bound to its Template by IRI (templateRef), and each FieldValue is joined to its corresponding EmbeddedField by an EmbeddedArtifactKey. The schema-side downward chain (Template → EmbeddedField → Field → FieldSpec) is the structural surface a template author defines; the instance-side downward chain (TemplateInstance → FieldValue → Value) is the runtime data the schema admits.

For the within-Field typed-variant hierarchy (the 20 concrete field families and their abstract groupings), see the next section.

Field Hierarchy

The diagram below shows the complete Field hierarchy and the FieldSpec each concrete field variant carries.

classDiagram
  class Field {
    <<abstract>>
  }
  class TemporalField {
    <<abstract>>
  }
  class EnumField {
    <<abstract>>
  }
  class ContactField {
    <<abstract>>
  }
  class ExternalAuthorityField {
    <<abstract>>
  }

  class TextField
  class NumericField
  class DateField
  class TimeField
  class DateTimeField
  class ControlledTermField
  class SingleValuedEnumField
  class MultiValuedEnumField
  class LinkField
  class EmailField
  class PhoneNumberField
  class OrcidField
  class RorField
  class DoiField
  class PubMedIdField
  class RridField
  class NihGrantIdField
  class AttributeValueField
  class IntegerNumberField
  class RealNumberField
  class BooleanField

  class TextFieldSpec
  class IntegerNumberFieldSpec
  class RealNumberFieldSpec
  class BooleanFieldSpec
  class DateFieldSpec
  class TimeFieldSpec
  class DateTimeFieldSpec
  class ControlledTermFieldSpec
  class SingleValuedEnumFieldSpec
  class MultiValuedEnumFieldSpec
  class LinkFieldSpec
  class EmailFieldSpec
  class PhoneNumberFieldSpec
  class OrcidFieldSpec
  class RorFieldSpec
  class DoiFieldSpec
  class PubMedIdFieldSpec
  class RridFieldSpec
  class NihGrantIdFieldSpec
  class AttributeValueFieldSpec

  Field <|-- TextField
  Field <|-- NumericField
  Field <|-- BooleanField
  Field <|-- TemporalField
  Field <|-- ControlledTermField
  Field <|-- EnumField
  Field <|-- LinkField
  Field <|-- ContactField
  Field <|-- ExternalAuthorityField
  Field <|-- AttributeValueField

  NumericField <|-- IntegerNumberField
  NumericField <|-- RealNumberField

  TemporalField <|-- DateField
  TemporalField <|-- TimeField
  TemporalField <|-- DateTimeField

  EnumField <|-- SingleValuedEnumField
  EnumField <|-- MultiValuedEnumField

  ContactField <|-- EmailField
  ContactField <|-- PhoneNumberField

  ExternalAuthorityField <|-- OrcidField
  ExternalAuthorityField <|-- RorField
  ExternalAuthorityField <|-- DoiField
  ExternalAuthorityField <|-- PubMedIdField
  ExternalAuthorityField <|-- RridField
  ExternalAuthorityField <|-- NihGrantIdField

  TextField --> TextFieldSpec : carries
  IntegerNumberField --> IntegerNumberFieldSpec : carries
  RealNumberField --> RealNumberFieldSpec : carries
  BooleanField --> BooleanFieldSpec : carries
  DateField --> DateFieldSpec : carries
  TimeField --> TimeFieldSpec : carries
  DateTimeField --> DateTimeFieldSpec : carries
  ControlledTermField --> ControlledTermFieldSpec : carries
  SingleValuedEnumField --> SingleValuedEnumFieldSpec : carries
  MultiValuedEnumField --> MultiValuedEnumFieldSpec : carries
  LinkField --> LinkFieldSpec : carries
  EmailField --> EmailFieldSpec : carries
  PhoneNumberField --> PhoneNumberFieldSpec : carries
  OrcidField --> OrcidFieldSpec : carries
  RorField --> RorFieldSpec : carries
  DoiField --> DoiFieldSpec : carries
  PubMedIdField --> PubMedIdFieldSpec : carries
  RridField --> RridFieldSpec : carries
  NihGrantIdField --> NihGrantIdFieldSpec : carries
  AttributeValueField --> AttributeValueFieldSpec : carries

Layered Specification

The CEDAR Template Model is specified across four normative chapters, each with a different concern:

A reusable conformance test suite accompanies the specification, embedded into serialization.md §8 via mdBook {{#include}}. It defines a cross-binding acceptance contract.

Cross-Cutting Conventions

A few structural conventions thread through every chapter:

• The kind discriminator. Every member of a discriminator: kind union (e.g. every Field family, every Value family, every EmbeddedField family) carries a kind property identifying its production, at every position it occupies on the wire. Productions that are not members of any kind-discriminated union (Cardinality, Annotation, LabelOverride, Property, etc.) never carry kind. The rule is uniform — see wire-grammar.md §1.5.
• Two-layer default values. Every concrete field family except AttributeValueField carries two layers of optional default value: a field-level default on the reusable Field’s FieldSpec, and an embedding-level default on the EmbeddedXxxField inside a Template. The embedding-level default overrides the field-level default when both are present. Defaults are UI/UX initialisation only — they do not appear in TemplateInstance artifacts and do not affect the RDF projection. See grammar.md §Defaults.
• Pinned lexical-form productions. The grammar’s primitive string types (SemanticVersion, IriString, Bcp47Tag, Iso8601DateTimeLexicalForm, AsciiIdentifier, IntegerLexicalForm) are normatively pinned to specific external specifications and regular expressions. See grammar.md §Primitive String Types.
• The error model. Conforming decoders and encoders report errors in three normatively-defined categories — wireShape, lexical, and structural — each with a JSON-pointer path locating the offending slot. See serialization.md §9.

Abstract Grammar

This section defines the abstract structure of the CEDAR Template Model using an EBNF-style grammar.

The grammar defines the abstract syntactic structure of the model. It specifies the kinds of constructs that exist and how they are composed, but it does not define a concrete textual or data serialization such as JSON, YAML, RDF, or a functional-style syntax.

Accordingly, a production in this grammar describes abstract structure rather than a directly parseable text form. In particular, a production such as Template ::= template( ... ) does not mean:

• the literal token template must appear in a file
• parentheses must appear in a file
• whitespace must be used in a particular way in a file
• the production is itself a concrete serialization format

The following notation is used throughout this grammar:

::=    defined as
|      alternative production
X*     zero or more occurrences of X
X+     one or more occurrences of X
[X]    optional occurrence of X
(...)  groups the named components of an abstract constructor form

Whitespace separates symbols within a production.

Production names use UpperCamelCase. A production name denotes the abstract category being defined, such as Template, Field, or DateFieldSpec.

Abstract constructor forms use lower_snake_case. In this document, a constructor form is the schematic form used to show how an abstract construct is composed, such as template(...), field(...), or date_field_spec(...). The difference between UpperCamelCase production names and lower_snake_case constructor forms is purely a visual distinction used to make it clear when the grammar is naming a category and when it is showing the abstract form of a construct belonging to that category.

For example, in the production

Template ::= template(
               TemplateId
               CatalogMetadata
               SchemaArtifactVersioning
               Title
               [TemplateRenderingHint]
               EmbeddedArtifact*
             )

Template is the production being defined, while template(...) denotes the abstract constructor form of that construct; in other words, it shows the components of a Template and how they are composed.

A conceptual overview of the model — describing the principal categories, their relationships, and the design rationale behind key decisions — is provided in spec/metamodel.md. The present document is the normative formal specification.

Contents

• Kernel Grammar
  • Core Structure
  • Concrete Field Artifacts
  • Embedded Artifacts
• Artifact Identity
• Artifact Metadata
  • Aggregate Structure
  • Descriptive Metadata
  • Lifecycle Metadata
  • Schema Versioning
  • Annotations
• Scalar and Datatype Leaves
  • Primitive String Types
  • Core IRI and String Types
  • Numeric Datatype Kind
• Values
  • Scalar Values
  • Temporal Values
  • Controlled Term Value
  • Enum Value
  • Link Value
  • Contact Values
  • External Authority Values
  • Attribute Value
• Embedded Artifact Properties
  • Embedded Artifact Key
  • References
  • Requirements
  • Cardinality
  • Visibility
  • Defaults
  • Label Override
  • Properties
• Field Specs
  • Temporal Field Specs
  • Controlled Term Sources
  • Rendering Hints
• Presentation Components
• Field Spec And Value Correspondence
• Instances
• Open Questions

Kernel Grammar

The kernel grammar defines the primary abstract categories of the model and the core schema-level structure that connects them. It introduces reusable schema artifacts, templates, and the embedding constructs through which templates assemble fields, nested templates, and presentation components. Subsequent sections refine the metadata, field-spec families, instance structures, and supporting constructs referenced here.

The diagram below gives an overview of the kernel. Template is the central container: it holds an ordered sequence of EmbeddedArtifact constructs, each of which contextualises a reusable artifact — a Field, a nested Template, or a PresentationComponent — within that specific template. A TemplateInstance records data conforming to a Template. Concrete Field variants and FieldSpec configurations are omitted for clarity.

%%{init: {'themeVariables': {'fontSize': '12px'}}}%%
classDiagram
  class Artifact {
    <<abstract>>
  }
  class SchemaArtifact {
    <<abstract>>
  }
  class Field {
    <<abstract>>
  }
  class Template {
    TemplateId
    ModelVersion
    CatalogMetadata
    SchemaArtifactVersioning
    Title
    [TemplateRenderingHint]
    [Header]
    [Footer]
  }
  class PresentationComponent {
    PresentationComponentId
    ModelVersion
    CatalogMetadata
  }
  class TemplateInstance {
    TemplateInstanceId
    ModelVersion
    CatalogMetadata
  }

  class EmbeddedArtifact {
    <<abstract>>
  }
  class EmbeddedField {
    EmbeddedArtifactKey
    [ValueRequirement]
    [Cardinality]
    [Visibility]
    [defaultValue]
    [LabelOverride]
    [HelpTextOverride]
    [Property]
  }
  class EmbeddedTemplate {
    EmbeddedArtifactKey
    [ValueRequirement]
    [Cardinality]
    [Visibility]
    [LabelOverride]
    [Property]
  }
  class EmbeddedPresentationComponent {
    EmbeddedArtifactKey
    [Visibility]
    [LabelOverride]
  }
  class Property {
    PropertyIri
    [PropertyLabel]
  }

  Artifact <|-- SchemaArtifact
  Artifact <|-- PresentationComponent
  Artifact <|-- TemplateInstance

  SchemaArtifact <|-- Field
  SchemaArtifact <|-- Template

  Template "1" *-- "0..*" EmbeddedArtifact : contains ordered

  EmbeddedArtifact <|-- EmbeddedField
  EmbeddedArtifact <|-- EmbeddedTemplate
  EmbeddedArtifact <|-- EmbeddedPresentationComponent

  EmbeddedField --> Field : references
  EmbeddedTemplate --> Template : references
  EmbeddedPresentationComponent --> PresentationComponent : references

  EmbeddedField ..> Property : carries
  EmbeddedTemplate ..> Property : carries

  TemplateInstance --> Template : conforms to

Core Structure

This subsection establishes the top-level taxonomy of the model and introduces its two principal concrete schema artifacts. Artifact is the broadest category, encompassing reusable schema artifacts, presentation components, and template instances. Template is defined here as the central container that organises embedded artifacts into a structured form. Field is introduced as an abstract category whose concrete variants are defined in the following subsection.

Artifact ::= SchemaArtifact
           | PresentationComponent
           | TemplateInstance

SchemaArtifact ::= Field
                 | Template

Template is a concrete schema artifact and the central container of the model. It assembles EmbeddedArtifact constructs into a structured form and defines the schema that TemplateInstance constructs conform to.

Template ::= template(
               TemplateId
               ModelVersion
               CatalogMetadata
               SchemaArtifactVersioning
               Title
               [TemplateRenderingHint]
               [Header]
               [Footer]
               EmbeddedArtifact*
             )

Title ::= title(
            MultilingualString
          )

Label ::= label(
            MultilingualString
          )

Header ::= header(
             MultilingualString
           )

Footer ::= footer(
             MultilingualString
           )

TemplateRenderingHint ::= template_rendering_hint(
                            [HelpDisplayMode]
                          )

HelpDisplayMode ::= "inline" | "tooltip" | "both" | "none"

Header and Footer denote optional human-readable textual content displayed at the top and bottom of a rendered template respectively. Each is a MultilingualString carrying one or more language-tagged localizations of the same conceptual text.

TemplateRenderingHint carries form-level UX configuration. Distinct from the per-field-spec RenderingHint family, which configures how a single field is rendered, TemplateRenderingHint configures behaviour that applies to the form as a whole. Currently the only slot is HelpDisplayMode; future revisions may add further form-level UX switches, each with its own cascade rule for embedded templates.

HelpDisplayMode selects how field HelpText — and any per-embedding HelpTextOverride — is presented at form-render time:

• "inline" — HelpText renders as visible text adjacent to the field, typically beneath the input.
• "tooltip" — HelpText renders as a hover/focus tooltip, triggered by a ? icon or similar affordance.
• "both" — both presentations are emitted. Useful for accessibility contexts where redundancy is preferred.
• "none" — the field’s HelpText is not displayed at form-render time. The content remains part of the model (visible to alternative renderers, to the RDF projection, and to catalog displays) but the form-rendering layer suppresses it.

When HelpDisplayMode is absent — either because the Template carries no TemplateRenderingHint, or because the hint omits the slot — the default behaviour is "inline".

The cascade rule for nested templates is a rendering-time concern, not a structural validation constraint, and is normatively stated in presentation.md: when a Template is embedded inside another Template, the inner template’s HelpDisplayMode is ignored for help-text rendering; the enclosing template’s setting applies to every field within the rendered form, including fields contributed by nested templates. The inner template’s own HelpDisplayMode applies only when the template is rendered standalone.

The following productions introduce the abstract field categories. Field remains an abstract category, while the intermediate categories group related concrete field artifacts for readability and shared semantics.

Field ::= TextField
        | NumericField
        | BooleanField
        | TemporalField
        | ControlledTermField
        | EnumField
        | LinkField
        | ContactField
        | ExternalAuthorityField
        | AttributeValueField

NumericField ::= IntegerNumberField
               | RealNumberField

TemporalField ::= DateField
                | TimeField
                | DateTimeField

EnumField ::= SingleValuedEnumField
            | MultiValuedEnumField

ContactField ::= EmailField
               | PhoneNumberField

ExternalAuthorityField ::= OrcidField
                         | RorField
                         | DoiField
                         | PubMedIdField
                         | RridField
                         | NihGrantIdField

Concrete Field Artifacts

Each concrete Field variant carries six components: a typed artifact identifier that permanently identifies the reusable field; a ModelVersion identifying the version of the CEDAR structural model the artifact conforms to; CatalogMetadata providing the descriptive, lifecycle, and annotation metadata used in catalog and registry contexts; SchemaArtifactVersioning providing the version, status, and lineage information common to all schema artifacts; a typed FieldSpec that specifies the value semantics and configuration for that field category; and a Label that carries the rendered question text shown to users at data-entry time. The identifier, FieldSpec, and Label are specific to each concrete variant; ModelVersion, CatalogMetadata, and SchemaArtifactVersioning are uniform across all fields. Each concrete Field MAY additionally carry an optional HelpText. The groupings below mirror the abstract Field hierarchy defined in Core Structure.

TextField, BooleanField, and the two numeric field families (IntegerNumberField and RealNumberField) are the simple scalar field specs. Each carries the most basic value semantics — free text, true / false, exact integer values, and real-valued numbers respectively.

TextField ↗ EmbeddedTextField ::= text_field(
               TextFieldId
               ModelVersion
               CatalogMetadata
               SchemaArtifactVersioning
               TextFieldSpec
               Label
               [HelpText]
             )

BooleanField ↗ EmbeddedBooleanField ::= boolean_field(
                  BooleanFieldId
                  ModelVersion
                  CatalogMetadata
                  SchemaArtifactVersioning
                  BooleanFieldSpec
                  Label
                  [HelpText]
                )

The numeric field variants correspond to the NumericField abstract category. They share the broader concept of numeric content but split semantically: IntegerNumberField carries arbitrary-precision integer values (no fractional part); RealNumberField carries real-valued numbers (decimal arbitrary precision, or IEEE 754 single- or double-precision floating point). The split is principled: integer arithmetic is exact and closed under the usual operations, whereas real-valued arithmetic carries approximation concerns. See Field Specs for the per-family configuration.

IntegerNumberField ↗ EmbeddedIntegerNumberField ::= integer_number_field(
                         IntegerNumberFieldId
                         ModelVersion
                         CatalogMetadata
                         SchemaArtifactVersioning
                         IntegerNumberFieldSpec
                         Label
                         [HelpText]
                       )

RealNumberField ↗ EmbeddedRealNumberField ::= real_number_field(
                      RealNumberFieldId
                      ModelVersion
                      CatalogMetadata
                      SchemaArtifactVersioning
                      RealNumberFieldSpec
                      Label
                      [HelpText]
                    )

The temporal field variants correspond to the TemporalField abstract category. Each is typed to a distinct temporal semantic — date, time of day, or combined date-time — and carries its own FieldSpec with precision and rendering options appropriate to that category.

DateField ↗ EmbeddedDateField ::= date_field(
               DateFieldId
               ModelVersion
               CatalogMetadata
               SchemaArtifactVersioning
               DateFieldSpec
               Label
               [HelpText]
             )

TimeField ↗ EmbeddedTimeField ::= time_field(
               TimeFieldId
               ModelVersion
               CatalogMetadata
               SchemaArtifactVersioning
               TimeFieldSpec
               Label
               [HelpText]
             )

DateTimeField ↗ EmbeddedDateTimeField ::= date_time_field(
                   DateTimeFieldId
                   ModelVersion
                   CatalogMetadata
                   SchemaArtifactVersioning
                   DateTimeFieldSpec
                   Label
                   [HelpText]
                 )

ControlledTermField supports values drawn from declared ontology sources. LinkField carries a single IRI-valued hyperlink.

ControlledTermField ↗ EmbeddedControlledTermField ::= controlled_term_field(
                          ControlledTermFieldId
                          ModelVersion
                          CatalogMetadata
                          SchemaArtifactVersioning
                          ControlledTermFieldSpec
                          Label
                          [HelpText]
                        )

LinkField ↗ EmbeddedLinkField ::= link_field(
               LinkFieldId
               ModelVersion
               CatalogMetadata
               SchemaArtifactVersioning
               LinkFieldSpec
               Label
               [HelpText]
             )

SingleValuedEnumField and MultiValuedEnumField correspond to the EnumField abstract category and are the two concrete enum field variants. They differ in whether they permit exactly one or multiple simultaneous selections from a declared set of permissible values. The permitted values are declared in the corresponding EnumFieldSpec and are validated against at the instance level.

SingleValuedEnumField ↗ EmbeddedSingleValuedEnumField ::= single_valued_enum_field(
                            SingleValuedEnumFieldId
                            ModelVersion
                            CatalogMetadata
                            SchemaArtifactVersioning
                            SingleValuedEnumFieldSpec
                            Label
                            [HelpText]
                          )

MultiValuedEnumField ↗ EmbeddedMultiValuedEnumField ::= multi_valued_enum_field(
                           MultiValuedEnumFieldId
                           ModelVersion
                           CatalogMetadata
                           SchemaArtifactVersioning
                           MultiValuedEnumFieldSpec
                           Label
                           [HelpText]
                         )

The contact field variants correspond to the ContactField abstract category and represent human contact identifiers.

EmailField ↗ EmbeddedEmailField ::= email_field(
                EmailFieldId
                ModelVersion
                CatalogMetadata
                SchemaArtifactVersioning
                EmailFieldSpec
                Label
                [HelpText]
              )

PhoneNumberField ↗ EmbeddedPhoneNumberField ::= phone_number_field(
                      PhoneNumberFieldId
                      ModelVersion
                      CatalogMetadata
                      SchemaArtifactVersioning
                      PhoneNumberFieldSpec
                      Label
                      [HelpText]
                    )

The external authority field variants correspond to the ExternalAuthorityField abstract category. Each represents an identifier issued by a specific external authority system, as described in the External Authority Values section. Each external authority field is associated with format validation specific to its identifier scheme and supports integration with the corresponding resolution service for identifier lookup and verification.

OrcidField ↗ EmbeddedOrcidField ::= orcid_field(
                OrcidFieldId
                ModelVersion
                CatalogMetadata
                SchemaArtifactVersioning
                OrcidFieldSpec
                Label
                [HelpText]
              )

RorField ↗ EmbeddedRorField ::= ror_field(
              RorFieldId
              ModelVersion
              CatalogMetadata
              SchemaArtifactVersioning
              RorFieldSpec
              Label
              [HelpText]
            )

DoiField ↗ EmbeddedDoiField ::= doi_field(
              DoiFieldId
              ModelVersion
              CatalogMetadata
              SchemaArtifactVersioning
              DoiFieldSpec
              Label
              [HelpText]
            )

PubMedIdField ↗ EmbeddedPubMedIdField ::= pub_med_id_field(
                    PubMedIdFieldId
                    ModelVersion
                    CatalogMetadata
                    SchemaArtifactVersioning
                    PubMedIdFieldSpec
                    Label
                    [HelpText]
                  )

RridField ↗ EmbeddedRridField ::= rrid_field(
               RridFieldId
               ModelVersion
               CatalogMetadata
               SchemaArtifactVersioning
               RridFieldSpec
               Label
               [HelpText]
             )

NihGrantIdField ↗ EmbeddedNihGrantIdField ::= nih_grant_id_field(
                     NihGrantIdFieldId
                     ModelVersion
                     CatalogMetadata
                     SchemaArtifactVersioning
                     NihGrantIdFieldSpec
                     Label
                     [HelpText]
                   )

AttributeValueField supports open-ended name-value pair data whose attribute names are not fixed at schema definition time.

AttributeValueField ↗ EmbeddedAttributeValueField ::= attribute_value_field(
                          AttributeValueFieldId
                          ModelVersion
                          CatalogMetadata
                          SchemaArtifactVersioning
                          AttributeValueFieldSpec
                          Label
                          [HelpText]
                        )

The concrete field artifacts defined above are reusable schema-level constructs. A reusable Field deliberately does not carry template-local keying, cardinality, visibility, or label override — those properties belong to the embedding context, not to the reusable artifact. To appear within a Template, each field must be included via an Embedded Artifacts construct, which adds that template-local context and governs how the field participates in that specific template.

Each concrete Field artifact MAY carry an optional HelpText slot. HelpText is authored guidance about what the field is asking for and how to answer — text typically rendered alongside the field at form-render time as inline help, as a hover tooltip, or both, controlled by the enclosing Template’s HelpDisplayMode. HelpText is distinct from Description: Description is the artifact-catalog explanation seen when browsing the field registry; HelpText is the form-author-facing guidance seen at data-entry time. The two roles often share text but serve different audiences.

HelpText ::= help_text( MultilingualString )

HelpText carries a MultilingualString value: localized authored guidance that may be presented in one or more natural languages. The enclosing Template’s HelpDisplayMode selects the presentation; absence of HelpDisplayMode defaults to "inline" rendering. The "none" arm suppresses rendering but preserves the content in the model (visible to alternative renderers, RDF projection, and catalog displays).

A per-embedding override is also defined: an EmbeddedField MAY carry an optional HelpTextOverride that replaces the field’s canonical HelpText at that embedding site only, mirroring the existing LabelOverride precedent. See Embedded Artifacts for the embedding-site shape.

Embedded Artifacts

An EmbeddedArtifact contextualises a reusable artifact within a specific Template, adding template-local properties that govern how the artifact participates in that context. There are three forms: EmbeddedField, which embeds a data-bearing field; EmbeddedTemplate, which nests a template within the containing template; and EmbeddedPresentationComponent, which contributes presentational structure without producing instance data.

The sequence of EmbeddedArtifact constructs within a Template is significant. The order in which they appear determines the presentation order of embedded artifacts in a rendered template. Conforming implementations MUST preserve this order.

EmbeddedArtifact ::= EmbeddedField
                   | EmbeddedTemplate
                   | EmbeddedPresentationComponent

EmbeddedField ::= EmbeddedTextField
                | EmbeddedIntegerNumberField
                | EmbeddedRealNumberField
                | EmbeddedBooleanField
                | EmbeddedDateField
                | EmbeddedTimeField
                | EmbeddedDateTimeField
                | EmbeddedControlledTermField
                | EmbeddedSingleValuedEnumField
                | EmbeddedMultiValuedEnumField
                | EmbeddedLinkField
                | EmbeddedEmailField
                | EmbeddedPhoneNumberField
                | EmbeddedOrcidField
                | EmbeddedRorField
                | EmbeddedDoiField
                | EmbeddedPubMedIdField
                | EmbeddedRridField
                | EmbeddedNihGrantIdField
                | EmbeddedAttributeValueField

Every concrete EmbeddedField variant follows the same structural pattern. Each carries: an EmbeddedArtifactKey uniquely identifying the embedding site within the containing Template; a typed field reference identifying the reusable Field being embedded; an optional ValueRequirement specifying whether a value is required, recommended, or optional; an optional Cardinality bounding the permitted number of values; an optional Visibility controlling whether the field is shown in rendered interfaces; an optional defaultValue providing an embedding-specific default whose type is the family-specific Value type (e.g. TextValue for EmbeddedTextField, DateValue for EmbeddedDateField); an optional LabelOverride allowing the template to override the field’s label in this context; and an optional Property associating a semantic property IRI with the embedding site. The only variation across concrete EmbeddedField variants is the typed field reference and the typed default value, both of which match the value family of the referenced field.

EmbeddedBooleanField and EmbeddedSingleValuedEnumField are the two exceptions to this pattern: each omits the [Cardinality] slot. A boolean field is inherently single-valued — its ValueRequirement slot already distinguishes the meaningful states (required, recommended, optional). A SingleValuedEnumField is similarly single-valued by construction; multi-valued enum embedding is expressed only through EmbeddedMultiValuedEnumField. EmbeddedMultiValuedEnumField further differs in that its embedding-level default is a sequence (EnumValue*) rather than a single optional value, parallel to how multi-valued enum instance values appear as a sequence in FieldValue.

EmbeddedTextField ↗ TextField ::= embedded_text_field(
                        EmbeddedArtifactKey
                        TextFieldId
                        [ValueRequirement]
                        [Cardinality]
                        [Visibility]
                        [TextValue]
                        [LabelOverride]
                        [HelpTextOverride]
                        [Property]
                      )

EmbeddedIntegerNumberField ↗ IntegerNumberField ::= embedded_integer_number_field(
                                 EmbeddedArtifactKey
                                 IntegerNumberFieldId
                                 [ValueRequirement]
                                 [Cardinality]
                                 [Visibility]
                                 [IntegerNumberValue]
                                 [LabelOverride]
                                 [HelpTextOverride]
                                 [Property]
                               )

EmbeddedRealNumberField ↗ RealNumberField ::= embedded_real_number_field(
                              EmbeddedArtifactKey
                              RealNumberFieldId
                              [ValueRequirement]
                              [Cardinality]
                              [Visibility]
                              [RealNumberValue]
                              [LabelOverride]
                              [HelpTextOverride]
                              [Property]
                            )

EmbeddedBooleanField ↗ BooleanField ::= embedded_boolean_field(
                           EmbeddedArtifactKey
                           BooleanFieldId
                           [ValueRequirement]
                           [Visibility]
                           [BooleanValue]
                           [LabelOverride]
                           [HelpTextOverride]
                           [Property]
                         )

EmbeddedDateField ↗ DateField ::= embedded_date_field(
                        EmbeddedArtifactKey
                        DateFieldId
                        [ValueRequirement]
                        [Cardinality]
                        [Visibility]
                        [DateValue]
                        [LabelOverride]
                        [HelpTextOverride]
                        [Property]
                      )

EmbeddedTimeField ↗ TimeField ::= embedded_time_field(
                        EmbeddedArtifactKey
                        TimeFieldId
                        [ValueRequirement]
                        [Cardinality]
                        [Visibility]
                        [TimeValue]
                        [LabelOverride]
                        [HelpTextOverride]
                        [Property]
                      )

EmbeddedDateTimeField ↗ DateTimeField ::= embedded_date_time_field(
                            EmbeddedArtifactKey
                            DateTimeFieldId
                            [ValueRequirement]
                            [Cardinality]
                            [Visibility]
                            [DateTimeValue]
                            [LabelOverride]
                            [HelpTextOverride]
                            [Property]
                          )

EmbeddedControlledTermField ↗ ControlledTermField ::= embedded_controlled_term_field(
                                  EmbeddedArtifactKey
                                  ControlledTermFieldId
                                  [ValueRequirement]
                                  [Cardinality]
                                  [Visibility]
                                  [ControlledTermValue]
                                  [LabelOverride]
                                  [HelpTextOverride]
                                  [Property]
                                )

EmbeddedSingleValuedEnumField ↗ SingleValuedEnumField ::= embedded_single_valued_enum_field(
                                    EmbeddedArtifactKey
                                    SingleValuedEnumFieldId
                                    [ValueRequirement]
                                    [Visibility]
                                    [EnumValue]
                                    [LabelOverride]
                                    [HelpTextOverride]
                                    [Property]
                                  )

EmbeddedMultiValuedEnumField ↗ MultiValuedEnumField ::= embedded_multi_valued_enum_field(
                                   EmbeddedArtifactKey
                                   MultiValuedEnumFieldId
                                   [ValueRequirement]
                                   [Cardinality]
                                   [Visibility]
                                   EnumValue*
                                   [LabelOverride]
                                   [HelpTextOverride]
                                   [Property]
                                 )

EmbeddedLinkField ↗ LinkField ::= embedded_link_field(
                        EmbeddedArtifactKey
                        LinkFieldId
                        [ValueRequirement]
                        [Cardinality]
                        [Visibility]
                        [LinkValue]
                        [LabelOverride]
                        [HelpTextOverride]
                        [Property]
                      )

EmbeddedEmailField ↗ EmailField ::= embedded_email_field(
                         EmbeddedArtifactKey
                         EmailFieldId
                         [ValueRequirement]
                         [Cardinality]
                         [Visibility]
                         [EmailValue]
                         [LabelOverride]
                         [HelpTextOverride]
                         [Property]
                       )

EmbeddedPhoneNumberField ↗ PhoneNumberField ::= embedded_phone_number_field(
                               EmbeddedArtifactKey
                               PhoneNumberFieldId
                               [ValueRequirement]
                               [Cardinality]
                               [Visibility]
                               [PhoneNumberValue]
                               [LabelOverride]
                               [HelpTextOverride]
                               [Property]
                             )

EmbeddedOrcidField ↗ OrcidField ::= embedded_orcid_field(
                         EmbeddedArtifactKey
                         OrcidFieldId
                         [ValueRequirement]
                         [Cardinality]
                         [Visibility]
                         [OrcidValue]
                         [LabelOverride]
                         [HelpTextOverride]
                         [Property]
                       )

EmbeddedRorField ↗ RorField ::= embedded_ror_field(
                       EmbeddedArtifactKey
                       RorFieldId
                       [ValueRequirement]
                       [Cardinality]
                       [Visibility]
                       [RorValue]
                       [LabelOverride]
                       [HelpTextOverride]
                       [Property]
                     )

EmbeddedDoiField ↗ DoiField ::= embedded_doi_field(
                       EmbeddedArtifactKey
                       DoiFieldId
                       [ValueRequirement]
                       [Cardinality]
                       [Visibility]
                       [DoiValue]
                       [LabelOverride]
                       [HelpTextOverride]
                       [Property]
                     )

EmbeddedPubMedIdField ↗ PubMedIdField ::= embedded_pub_med_id_field(
                            EmbeddedArtifactKey
                            PubMedIdFieldId
                            [ValueRequirement]
                            [Cardinality]
                            [Visibility]
                            [PubMedIdValue]
                            [LabelOverride]
                            [HelpTextOverride]
                            [Property]
                          )

EmbeddedRridField ↗ RridField ::= embedded_rrid_field(
                        EmbeddedArtifactKey
                        RridFieldId
                        [ValueRequirement]
                        [Cardinality]
                        [Visibility]
                        [RridValue]
                        [LabelOverride]
                        [HelpTextOverride]
                        [Property]
                      )

EmbeddedNihGrantIdField ↗ NihGrantIdField ::= embedded_nih_grant_id_field(
                               EmbeddedArtifactKey
                               NihGrantIdFieldId
                               [ValueRequirement]
                               [Cardinality]
                               [Visibility]
                               [NihGrantIdValue]
                               [LabelOverride]
                               [HelpTextOverride]
                               [Property]
                             )

EmbeddedAttributeValueField ↗ AttributeValueField ::= embedded_attribute_value_field(
                                  EmbeddedArtifactKey
                                  AttributeValueFieldId
                                  [ValueRequirement]
                                  [Cardinality]
                                  [Visibility]
                                  [LabelOverride]
                                  [HelpTextOverride]
                                  [Property]
                                )

EmbeddedTemplate and EmbeddedPresentationComponent follow a similar pattern to embedded fields but differ in what embedding properties they carry. EmbeddedTemplate supports cardinality to permit multiple nested instances of the referenced template, carries no typed default value, and carries an optional Property associating a semantic property IRI with the embedding site. EmbeddedPresentationComponent carries neither a value requirement, cardinality, default value, label override, nor property, as it contributes no instance data and exists purely to contribute presentational structure. The only embedding-level property it carries is Visibility.

EmbeddedTemplate ::= embedded_template(
                       EmbeddedArtifactKey
                       TemplateId
                       [ValueRequirement]
                       [Cardinality]
                       [Visibility]
                       [LabelOverride]
                       [Property]
                     )

EmbeddedPresentationComponent ::= embedded_presentation_component(
                                    EmbeddedArtifactKey
                                    PresentationComponentId
                                    [Visibility]
                                  )

Artifact Identity

Artifact identity defines the typed identifiers by which artifacts and artifact references are denoted in the model. These identity constructs are distinct from descriptive metadata, lifecycle metadata, versioning, and annotations.

Each field kind has its own typed identifier rather than sharing a single generic FieldId. This provides strong typing: an EmbeddedTextField can only carry a TextFieldId at its artifactRef slot, an EmbeddedDateField can only carry a DateFieldId, and so on, making it structurally impossible to embed a field of the wrong type. TemplateId, PresentationComponentId, and TemplateInstanceId follow the same pattern for the same reason.

Identifiers serve two roles: at the definition site of a reusable artifact (e.g. Field.id, Template.id) they permanently name the artifact; at the embedding site (e.g. EmbeddedField.artifactRef, EmbeddedTemplate.artifactRef) they reference the artifact being embedded. The same typed identifier production is used at both positions; the role distinction is conveyed by the surrounding production’s component name.

FieldId ::= TextFieldId
          | IntegerNumberFieldId
          | RealNumberFieldId
          | BooleanFieldId
          | DateFieldId
          | TimeFieldId
          | DateTimeFieldId
          | ControlledTermFieldId
          | SingleValuedEnumFieldId
          | MultiValuedEnumFieldId
          | LinkFieldId
          | EmailFieldId
          | PhoneNumberFieldId
          | OrcidFieldId
          | RorFieldId
          | DoiFieldId
          | PubMedIdFieldId
          | RridFieldId
          | NihGrantIdFieldId
          | AttributeValueFieldId

TextFieldId ::= text_field_id( Iri )

IntegerNumberFieldId ::= integer_number_field_id( Iri )

RealNumberFieldId ::= real_number_field_id( Iri )

BooleanFieldId ::= boolean_field_id( Iri )

DateFieldId ::= date_field_id( Iri )

TimeFieldId ::= time_field_id( Iri )

DateTimeFieldId ::= date_time_field_id( Iri )

ControlledTermFieldId ::= controlled_term_field_id( Iri )

SingleValuedEnumFieldId ::= single_valued_enum_field_id( Iri )

MultiValuedEnumFieldId ::= multi_valued_enum_field_id( Iri )

LinkFieldId ::= link_field_id( Iri )

EmailFieldId ::= email_field_id( Iri )

PhoneNumberFieldId ::= phone_number_field_id( Iri )

OrcidFieldId ::= orcid_field_id( Iri )

RorFieldId ::= ror_field_id( Iri )

DoiFieldId ::= doi_field_id( Iri )

PubMedIdFieldId ::= pub_med_id_field_id( Iri )

RridFieldId ::= rrid_field_id( Iri )

NihGrantIdFieldId ::= nih_grant_id_field_id( Iri )

AttributeValueFieldId ::= attribute_value_field_id( Iri )

TemplateId ::= template_id( Iri )

PresentationComponentId ::= presentation_component_id( Iri )

TemplateInstanceId ::= template_instance_id( Iri )

All artifact identifier productions are IRI-valued. See Iri.

Concrete serializations need not preserve the per-family identifier distinctions drawn here. In the JSON wire encoding, every artifact identifier — whether a per-family FieldId variant such as TextFieldId or SingleValuedEnumFieldId, or one of the non-field identifiers TemplateId, PresentationComponentId, and TemplateInstanceId — is encoded as a bare IRI string with no per-family discriminator. The field family of a FieldId reference is recovered from the kind of the enclosing Field or EmbeddedField. See wire-grammar.md §5 and serialization.md.

Artifact Metadata

Artifact metadata defines descriptive information, lifecycle information, versioning, and annotations. CatalogMetadata is uniform across every artifact kind and provides the common catalog-oriented metadata carried by all artifacts other than identity: descriptive properties (preferred catalog label, description, identifier, alternative labels), lifecycle metadata, and annotations. Schema artifacts (Field, Template) additionally carry SchemaArtifactVersioning as a separate top-level slot recording version, status, and lineage.

Aggregate Structure

This subsection identifies how the metadata categories are grouped at the artifact level. CatalogMetadata carries the catalog-oriented properties of an artifact — descriptive properties (preferred catalog label, description, identifier, alternative labels), lifecycle metadata, and annotations — directly as members. It is uniform across every artifact kind: Field, Template, PresentationComponent, and TemplateInstance all carry the same CatalogMetadata shape.

The schema artifacts (Field and Template) additionally carry SchemaArtifactVersioning as a separate top-level slot on the artifact itself; non-schema artifacts (PresentationComponent, TemplateInstance) do not carry versioning.

CatalogMetadata is distinct from an artifact’s rendered display name. A Field carries a top-level Label slot (the rendered question text); a Template carries a top-level Title slot (the rendered form title); a TemplateInstance MAY carry an optional Label (a user-supplied instance name); a PresentationComponent carries no rendered display name at all. These rendered slots are defined on the per-artifact productions in Field Artifacts, Core Structure, Instances, and Presentation Components respectively.

CatalogMetadata ::= catalog_metadata(
                      [PreferredLabel]
                      [Description]
                      [Identifier]
                      AlternativeLabel*
                      LifecycleMetadata
                      Annotation*
                    )

Descriptive Metadata

The descriptive metadata of an artifact comprises a set of human-oriented properties carried directly by CatalogMetadata. These properties support naming, explanatory text, and external or local identifiers used for cataloging. PreferredLabel, when present, is the artifact’s preferred display name in catalog and registry contexts (e.g., browsing the field registry or listing templates) — distinct from the artifact’s rendered display name, which lives in a top-level slot on the artifact itself (Field.label, Template.title, TemplateInstance.label). Authors typically populate PreferredLabel with the same text as the rendered slot; the two are separate so they MAY differ when needed (for example, a field whose registry name is "Comment field (v1.2)" may render in forms as just "Comment"). Description, when present, is an extended textual explanation of the artifact’s purpose and content, intended for catalog display. Identifier, when present, is a user-specified external identifier intended for integration with institutional or external systems. AlternativeLabel, when present, provides additional display labels for the artifact (synonyms, abbreviations, legacy labels carried forward from prior versions of the model).

Description ::= description(
                  MultilingualString
                )

Identifier ::= identifier(
                 string
               )

Description carries a MultilingualString value: human-readable text that may be presented in one or more natural languages. Identifier carries an arbitrary Unicode string value: it is a technical user-supplied key intended for integration with external systems and is not a human-display label, so it is not multilingual. PreferredLabel is defined in the Controlled Term Value section; AlternativeLabel is defined in the Label Override section. Both are MultilingualString-valued.

Lifecycle Metadata

LifecycleMetadata identifies when an artifact was created and modified, and which agents were responsible for those actions.

LifecycleMetadata ::= lifecycle_metadata(
                        CreatedOn
                        CreatedBy
                        ModifiedOn
                        ModifiedBy
                      )

CreatedOn ::= IsoDateTimeStamp

CreatedBy ::= Iri

ModifiedOn ::= IsoDateTimeStamp

ModifiedBy ::= Iri

CreatedOn and ModifiedOn MUST be ISO 8601 date-time timestamps.

CreatedBy and ModifiedBy denote IRIs identifying the responsible agents.

See IsoDateTimeStamp and Iri.

Schema Versioning

SchemaArtifactVersioning identifies version-related metadata specific to reusable schema artifacts. It captures artifact version, publication status, and optional derivation links to earlier or source artifacts.

SchemaArtifactVersioning ::= schema_artifact_versioning(
                       Version
                       Status
                       [PreviousVersion]
                       [DerivedFrom]
                     )

Version ::= version(
              SemanticVersion
            )

Status ::= "draft" | "published"

ModelVersion ::= model_version(
                   SemanticVersion
                 )

PreviousVersion ::= previous_version(
                      Iri
                    )

DerivedFrom ::= derived_from(
                  Iri
                )

Version denotes a Semantic Versioning 2.0.0 version identifier.

Status denotes the publication status of a reusable schema artifact and is restricted to draft or published.

PreviousVersion and DerivedFrom denote IRIs identifying related source or predecessor artifacts.

The combined meaning of these fields and their interaction with artifact identity is specified in Versioning Model below.

Versioning Model

The CEDAR versioning model rests on one guiding rule: identity is per-version. Every version of a Field or Template is itself a distinct Artifact with its own IRI. There is no separate “version-independent” identifier for the conceptual artifact; what holds successive versions together is the PreviousVersion link from each artifact to the one it replaces.

Identity and immutability. Every reusable schema artifact (every Field and every Template) is identified by a single SchemaArtifactId (a FieldId or TemplateId). That IRI denotes one specific version: distinct versions of “the same” artifact are distinct artifacts in the model, each with its own IRI. A published artifact MUST be treated as immutable — once Status is "published", the content addressed by its IRI MUST NOT change. A draft artifact MAY be edited in place while its Status remains "draft". The transition from draft to published is one-way: an artifact whose Status is "published" MUST NOT transition back to "draft".

Creating a new version. To produce a revised version of a published artifact, mint a new IRI, allocate a new artifact at that IRI with Status set to "draft", and set PreviousVersion to the IRI of the artifact being revised. Editing happens on the new draft; once the new artifact is itself published, it joins the version chain and becomes immutable in turn. The published predecessor is unaffected by the existence of its successor: it remains addressable at its own IRI and continues to be a valid target for TemplateInstance references.

Version chains. Successive versions of an artifact form a version chain: a sequence of distinct artifacts, each with its own IRI, linked by PreviousVersion. Artifact B is the immediate successor of artifact A when B.previousVersion = A.id. The first artifact in a chain MUST omit PreviousVersion. Every subsequent artifact in the chain MUST set PreviousVersion to the IRI of its immediate predecessor. A chain is therefore a singly-linked list of IRIs, traversable backwards from any version to the original.

The role of Version. Version carries a Semantic Versioning identifier as advisory metadata describing this artifact’s place in its chain (e.g. 1.0.0 → 1.1.0 for a backwards-compatible change, 1.0.0 → 2.0.0 for a breaking change). The pairing of IRI and PreviousVersion is what authoritatively establishes the chain; Version is descriptive and is not load-bearing for chain identity. Successive artifacts in a chain SHOULD carry monotonically increasing SemanticVersion values, but this specification does not impose a structural constraint to that effect.

Derivation versus succession. DerivedFrom and PreviousVersion are distinct relationships and answer different questions. PreviousVersion records succession within a single version chain: the successor is intended to replace its predecessor as the same conceptual artifact evolves. DerivedFrom records non-version lineage: the new artifact is a fork or adaptation — it was authored by copying or modifying an existing artifact, but it is not the next version of that artifact. A fork begins its own independent version chain. Typical uses of DerivedFrom include adopting a community-published template into an institutional namespace or spawning a specialised variant of an existing field. An artifact MAY carry both PreviousVersion and DerivedFrom simultaneously: the artifact succeeds another within its own chain and was originally derived from a separate source artifact. The two relationships are independent. PreviousVersion and DerivedFrom, when both present, MUST NOT carry the same IRI value — succession and derivation are mutually exclusive at any single point.

Summary of normative rules.

1. Every version of a Field or Template MUST have a distinct IRI.
2. A published artifact MUST NOT change at its IRI.
3. A published artifact MUST NOT transition back to draft.
4. The first artifact in a version chain MUST omit PreviousVersion. Every other artifact in the chain MUST set PreviousVersion to the IRI of its immediate predecessor in that chain.
5. When both PreviousVersion and DerivedFrom are present on the same artifact, they MUST NOT carry the same IRI.

Annotations

Annotation provides an extensible metadata mechanism for additional named metadata values that are not captured by the core descriptive, lifecycle, or versioning structures. The first Iri identifies the annotation property — the predicate IRI under which the annotation is asserted. The AnnotationValue is the associated metadata value, currently a string-bearing scalar or an IRI. This supports linking to external resources such as DOIs and grant identifiers, as well as storing institutional metadata.

Annotation ::= annotation(
                 Iri
                 AnnotationValue
               )

AnnotationValue ::= AnnotationStringValue
                  | AnnotationIriValue

AnnotationStringValue ::= annotation_string_value(
                            LexicalForm
                            [LanguageTag]
                          )

AnnotationIriValue ::= annotation_iri_value(
                         Iri
                       )

AnnotationValue is a discriminated union over named annotation-value productions. The two currently defined variants represent text-valued and IRI-valued annotations: AnnotationStringValue carries a lexical form with an optional language tag; AnnotationIriValue carries an IRI denoting a resource. AnnotationStringValue does not carry an explicit datatype; lexically-typed annotations are not modelled at this position, since annotation metadata is by convention either text or IRI-valued.

The variant family is open to extension. A future revision MAY introduce additional AnnotationXxxValue productions (for example, integer- or real-number-valued annotations) without breaking the existing variants.

Scalar and Datatype Leaves

The following productions define the primitive leaf types used throughout this grammar. They represent the atomic constructs from which all other productions are built: IRIs, typed string domains, lexical forms, multilingual textual metadata, numeric and temporal datatype IRIs, and textual metadata values.

Primitive String Types

The following nonterminals are the string-valued leaf types referenced by the productions in this section. Each is pinned to a specific external specification or regular expression so that implementations can validate inputs unambiguously.

• SemanticVersion — a Semantic Versioning 2.0.0 string. MUST conform to the Semantic Versioning 2.0.0 specification at semver.org, specifically the regular expression in the SemVer FAQ (https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string). Examples: 1.0.0, 2.0.0-alpha.1, 1.0.0+build.7.

• IriString — the lexical form of an IRI as defined by RFC 3987 §2.2 (the IRI production). The IRI MUST be absolute (carry a scheme); relative IRIs are not permitted at any wire-form position. Implementations SHOULD use the RFC 3987 IRI ABNF; a permissive practical regex is ^[A-Za-z][A-Za-z0-9+.\-]*:[^\s<>"]+$ but this is not sufficient for full conformance.

• Bcp47Tag — a well-formed BCP 47 language tag per RFC 5646, specifically the Language-Tag production. Implementations SHOULD validate against the IANA Language Subtag Registry; a syntactic-only check (well-formedness without registry lookup) is acceptable as a baseline. Examples: en, en-US, zh-Hant-TW, de-CH-1901.

• Iso8601DateTimeLexicalForm — an ISO 8601 combined date-and-time string in the extended format with full date and full time, with or without a UTC offset. The accepted shapes are:

  • YYYY-MM-DDTHH:MM:SS (no offset)
  • YYYY-MM-DDTHH:MM:SS.sss (fractional seconds, 1–9 digits)
  • YYYY-MM-DDTHH:MM:SSZ (UTC)
  • YYYY-MM-DDTHH:MM:SS±HH:MM (offset)
  • the same shapes with .sss fractional seconds combined with the timezone form.

  This corresponds to the XSD dateTime lexical form (XSD 1.1 §3.3.7). Examples: 2026-05-08T14:30:00Z, 2026-05-08T14:30:00.123-07:00.

• AsciiIdentifier — a string matching the regular expression ^[A-Za-z][A-Za-z0-9_-]*$: an ASCII letter followed by zero or more ASCII letters, digits, underscores, or hyphens. Length is unbounded. Examples: topic, field-1, Member_42.

• IntegerLexicalForm — a base-10 signed integer literal matching the regular expression ^-?(0|[1-9][0-9]*)$: an optional leading minus sign followed by either 0 or a non-zero digit and zero or more digits. Leading zeros and a leading + are not permitted. Magnitude is unbounded. The using context may further restrict the sign — NonNegativeInteger rejects values with a leading minus sign; signed bounds productions accept it.

Core IRI and String Types

This subsection defines the fundamental IRI, string, and numeric leaf types that appear throughout the grammar. Iri is the base construct for all IRI-valued positions. TermIri is a specialised IRI form for controlled-vocabulary references. LanguageTag and LexicalForm are leaf string types used by Value constructs that carry localized or lexically-typed content. IsoDateTimeStamp carries ISO 8601 date-time values used in lifecycle metadata. NonNegativeInteger supports field-spec constraints.

Iri ::= iri(
          IriString
        )

TermIri ::= term_iri(
              Iri
            )

LanguageTag ::= language_tag(
                  Bcp47Tag
                )

LexicalForm ::= lexical_form(
                  string
                )

IsoDateTimeStamp ::= iso_date_time_stamp(
                       Iso8601DateTimeLexicalForm
                     )

NonNegativeInteger ::= non_negative_integer(
                         IntegerLexicalForm
                       )

Iri denotes an Internationalized Resource Identifier. It corresponds to the xsd:anyURI datatype; implementations MAY represent it as a plain string provided it is a syntactically valid IRI.

TermIri denotes an Iri that identifies a term in a controlled vocabulary or ontology. It is used in ControlledTermValue, ControlledTermClass, and Meaning.

LanguageTag denotes a well-formed BCP 47 language tag.

LexicalForm denotes a Unicode string and SHOULD be in Unicode Normalization Form C.

IsoDateTimeStamp denotes an ISO 8601 date-time lexical form.

NonNegativeInteger denotes an integer greater than or equal to zero.

Multilingual Strings

LangString and MultilingualString are the constructs used at every grammar position that carries human-display text. They distinguish localizations of one conceptual string from technical Unicode-string keys (which remain plain string-valued; see Identifier and the controlled-term-source identifiers in Controlled Term Sources).

LangString ::= lang_string(
                 string
                 Bcp47Tag
               )

MultilingualString ::= multilingual_string(
                         LangString+
                       )

LangString pairs a textual value with a BCP 47 language tag identifying its natural language.

MultilingualString denotes a non-empty set of LangString entries representing localizations of one conceptual string. The entries’ language tags MUST be unique within a MultilingualString (case-folded comparison): the construct represents a set of localizations, not a list of phrasings within a single language.

The 'und' (undetermined) BCP 47 subtag MAY be used to denote a LangString whose natural language is unspecified. Implementations MAY use 'und' as the default tag when constructing a MultilingualString from a bare string with no language information.

MultilingualString differs from a single language-tagged scalar value (such as TextValue with a LanguageTag) in that it carries an unweighted localization set — multiple language tags coexist for the same conceptual string at metadata positions such as Template.header or CatalogMetadata.preferredLabel.

Numeric Datatype Kind

IntegerNumberValue is fixed to a single integer category; its datatype is implicit and is not a configurable component of the production. RealNumberValue carries an explicit RealNumberDatatypeKind chosen from three alternatives — decimal, float, or double. The kind names are CEDAR-native enum values; their corresponding XSD datatype IRIs are defined externally to the abstract grammar by rdf-projection.md.

RealNumberDatatypeKind ::= "decimal" | "float" | "double"

decimal denotes exact arbitrary-precision decimal numbers. float and double denote IEEE 754 single- and double-precision floating-point numbers respectively.

This specification narrows the supported numeric kinds to four (one integer kind plus the three real-number kinds). Earlier drafts admitted the full XSD numeric hierarchy (16 datatypes including long, short, byte, the signed/unsigned bounded subtypes, and the sign-constrained subtypes such as nonNegativeInteger); those are not part of the conforming set. Sign and range constraints are expressed via IntegerNumberMinValue / IntegerNumberMaxValue (or the real-valued equivalents). Bit-precision distinctions are not modelled at the type level; decimal covers exact arbitrary precision when needed, and float / double cover IEEE 754 single- and double-precision when storage precision matters.

Values

This section defines the Value types that represent instance-level data. Value constructs appear in FieldValue instances and as typed default values in EmbeddedArtifact properties. The value types are defined here independently of the FieldSpec productions that constrain them; the normative mapping between each FieldSpec and its permitted Value form is given in the Field Spec And Value Correspondence section.

Value ::= TextValue
        | NumericValue
        | BooleanValue
        | DateValue
        | TimeValue
        | DateTimeValue
        | ControlledTermValue
        | EnumValue
        | LinkValue
        | EmailValue
        | PhoneNumberValue
        | ExternalAuthorityValue
        | AttributeValue

NumericValue ::= IntegerNumberValue
               | RealNumberValue

Scalar Values

TextValue, BooleanValue, and the two numeric value forms (IntegerNumberValue and RealNumberValue) are the simplest value types. Each carries the family-specific content directly: a lexical form for the string-bearing variants, a boolean payload for BooleanValue. TextValue carries an optional LanguageTag; when present, the value is a language-tagged string, when absent, a plain string. IntegerNumberValue carries a base-10 integer lexical form; its category is implicit and not carried as a component. RealNumberValue carries a base-10 real-valued lexical form paired with an explicit RealNumberDatatypeKind (decimal, float, or double).

TextValue ::= text_value(
                LexicalForm
                [LanguageTag]
              )

IntegerNumberValue ::= integer_number_value(
                         LexicalForm
                       )

RealNumberValue ::= real_number_value(
                      LexicalForm
                      RealNumberDatatypeKind
                    )

BooleanValue ::= boolean_value(
                   boolean
                 )

IntegerNumberValue’s lexical form MUST be a base-10 integer literal (per the IntegerLexicalForm primitive in §Primitive String Types). RealNumberValue’s lexical form is a base-10 real-valued literal whose admissible form depends on the carried datatype: decimal admits an arbitrary-precision decimal lexical form; float and double admit IEEE 754-style lexical forms (including special values such as INF, -INF, and NaN).

NumericValue is the abstract category admitting IntegerNumberValue and RealNumberValue; the two are distinct concrete value types and a FieldValue carrying numeric content discriminates between them by kind.

The lexical form of any string-bearing value SHOULD be in Unicode Normalization Form C.

A Value whose lexical form lies outside the lexical space of its declared datatype is ill-typed: it is not syntactically ill-formed but does not determine a valid value. Implementations MUST accept ill-typed values and MAY produce warnings when encountering them. The corresponding RDF projection (see rdf-projection.md) preserves the ill-typed lexical form.

Temporal Values

Temporal values represent date, time, and date-time data, corresponding directly to DateFieldSpec, TimeFieldSpec, and DateTimeFieldSpec respectively. DateValue is further refined into three precision variants — YearValue, YearMonthValue, and FullDateValue. Each temporal Value variant carries a LexicalForm directly; the temporal category is fixed by the variant’s kind. FullDateValue carries an ISO 8601 calendar-date lexical form; TimeValue carries an ISO 8601 time-of-day lexical form; DateTimeValue carries an ISO 8601 combined date-time lexical form. YearValue and YearMonthValue carry plain strings matching the patterns YYYY and YYYY-MM respectively. The RDF projection of these values is defined separately in rdf-projection.md.

DateValue ::= YearValue
            | YearMonthValue
            | FullDateValue

YearValue ::= year_value(
                LexicalForm    (* matches YYYY, e.g. "2024" *)
              )

YearMonthValue ::= year_month_value(
                     LexicalForm    (* matches YYYY-MM, e.g. "2024-06" *)
                   )

FullDateValue ::= full_date_value(
                    LexicalForm
                  )

TimeValue ::= time_value(
                LexicalForm
              )

DateTimeValue ::= date_time_value(
                    LexicalForm
                  )

Controlled Term Value

A controlled term value identifies a term drawn from an ontology, branch, class set, or value set declared in the corresponding ControlledTermFieldSpec. It carries a TermIri identifying the term, together with an optional human-readable Label and optional Notation and PreferredLabel terminology metadata from the source ontology. Label is the display label intended for end-user presentation; Notation is a symbolic code (typically a SKOS notation) bound to the term; PreferredLabel is the ontology’s own preferred label for the term, distinct from the display Label that may have been customized for the surrounding context.

A ControlledTermValue MAY omit Label: a consumer that has access to the source ontology can resolve the term’s display label from the TermIri. Producers SHOULD include Label when it is known at the point of value construction so that downstream consumers without ontology access can render the value.

Label ::= label(
            MultilingualString
          )

Notation ::= notation(
               string
             )

PreferredLabel ::= preferred_label(
                     MultilingualString
                   )

ControlledTermValue ::= controlled_term_value(
                          TermIri
                          [Label]
                          [Notation]
                          [PreferredLabel]
                        )

Label and PreferredLabel are MultilingualString values: each carries one or more language-tagged localizations of the term’s display label. Notation is a plain Unicode string: it is a technical symbolic code (typically a SKOS notation) rather than human-display text, and is therefore not multilingual.

Enum Value

An enum value carries a selection from the permissible values declared by an EnumFieldSpec. Every enum value is identified by a Token — a non-empty Unicode string that serves as the canonical key of one of the enum spec’s PermissibleValue entries. A conforming instance value MUST equal the Token of one of the referenced spec’s permissible values.

EnumValue ::= enum_value(
                Token
              )

Token is the leaf type used as the canonical key of an enum selection. It is defined in the Field Specs section alongside the related leaf productions (PermissibleValue, Meaning) used by EnumFieldSpec.

Link Value

A link value represents a hyperlink or URL-valued field. It carries an Iri identifying the linked resource and an optional Label providing a human-readable display label for the link.

LinkValue ::= link_value(
                Iri
                [Label]
              )

Label is the same MultilingualString-valued production used by ControlledTermValue, PermissibleValue, and the external-authority value types: a label is treated uniformly as a localizable display string. A hyperlink’s display text MAY therefore carry one or more language-tagged localizations.

Contact Values

Contact values represent human contact identifiers. EmailValue carries an email address as a plain LexicalForm; PhoneNumberValue carries a telephone number as a plain LexicalForm. Format validation is left to implementations.

EmailValue ::= email_value(
                 LexicalForm
               )

PhoneNumberValue ::= phone_number_value(
                       LexicalForm
                     )

External Authority Values

External authority values represent identifiers issued by recognised external authority systems. Each concrete value type carries a typed IRI specialised for its authority together with an optional human-readable Label. The typed IRI signals the expected identifier scheme; format conformance for each authority may be enforced by profile-specific or implementation-specific validation rules.

ExternalAuthorityValue ::= OrcidValue
                         | RorValue
                         | DoiValue
                         | PubMedIdValue
                         | RridValue
                         | NihGrantIdValue

OrcidValue ::= orcid_value(
                 OrcidIri
                 [Label]
               )

RorValue ::= ror_value(
               RorIri
               [Label]
             )

DoiValue ::= doi_value(
               DoiIri
               [Label]
             )

PubMedIdValue ::= pub_med_id_value(
                    PubMedIri
                    [Label]
                  )

RridValue ::= rrid_value(
                RridIri
                [Label]
              )

NihGrantIdValue ::= nih_grant_id_value(
                      NihGrantIri
                      [Label]
                    )

OrcidIri    ::= orcid_iri( Iri )
RorIri      ::= ror_iri( Iri )
DoiIri      ::= doi_iri( Iri )
PubMedIri   ::= pub_med_iri( Iri )
RridIri     ::= rrid_iri( Iri )
NihGrantIri ::= nih_grant_iri( Iri )

The final character of an ORCID iD MAY be X, serving as an ISO 7064 Mod 11-2 check character.

Attribute Value

An attribute value is a name-value pair used to represent arbitrary named properties whose names are not known at schema definition time. AttributeName carries the name of the attribute as a Unicode string. The value component is itself a Value, permitting attribute values to carry any value type including nested attribute values. Nesting depth is unbounded at the model level; concrete implementations MAY impose practical limits.

AttributeName ::= attribute_name(
                    string
                  )

AttributeValue ::= attribute_value(
                     AttributeName
                     Value
                   )

Embedded Artifact Properties

Embedded artifact properties define the contextual information carried by an EmbeddedArtifact within a Template. These properties govern how a referenced reusable artifact is used in that template context, including key, reference, requirement, cardinality, visibility, defaults, and label override, and they are distinct from the intrinsic properties of the referenced reusable artifact itself.

Embedded Artifact Key

An EmbeddedArtifactKey is the local identifier of an EmbeddedArtifact within a Template. It is the key by which an embedded field, embedded template, or embedded presentation component is distinguished from other embedded artifacts in the same template. This key is also the mechanism that connects template structure to instance structure: FieldValue and NestedTemplateInstance use EmbeddedArtifactKey to identify which embedded artifact in the template they correspond to.

EmbeddedArtifactKey ::= embedded_artifact_key(
                          AsciiIdentifier
                        )

EmbeddedArtifactKey MUST match the pattern [A-Za-z][A-Za-z0-9_-]*: it MUST begin with an ASCII letter followed by zero or more ASCII letters, digits, underscores, or hyphens.

EmbeddedArtifactKey values are local to a Template and MUST be unique within that Template.

EmbeddedArtifactKey is distinct from artifact identifiers such as FieldId and TemplateId. It identifies the embedding site within a template rather than the reusable artifact being referenced. The same reusable Field may be embedded more than once in a Template under different keys, and each key independently identifies that embedding site in both the template structure and any corresponding TemplateInstance.

Requirements

ValueRequirement identifies whether a value is required, recommended, or optional in the embedding context. Required means that a value must be supplied for conformance. Recommended and Optional are identical for conformance purposes: absence of a value MUST NOT cause conformance failure in either case. The distinction is one of authoring guidance only: implementations SHOULD encourage entry for Recommended fields and MAY issue warnings when such fields are left empty.

ValueRequirement ::= "required" | "recommended" | "optional"

When ValueRequirement is absent from an EmbeddedArtifact, the default is "optional".

Cardinality

Cardinality identifies the permitted number of occurrences for the embedded artifact in the embedding context.

Cardinality ::= cardinality(
                  MinCardinality
                  [MaxCardinality]
                )

MinCardinality ::= min_cardinality(
                     NonNegativeInteger
                   )

MaxCardinality ::= max_cardinality(
                     NonNegativeInteger
                   )

When MaxCardinality is absent from a present Cardinality, the cardinality is unbounded above: any number of occurrences greater than or equal to the specified MinCardinality is permitted. Unboundedness is therefore expressed by omission of MaxCardinality rather than by a distinct construct.

When Cardinality is absent from an EmbeddedArtifact, the implied default is min_cardinality(1) with max_cardinality(1): the embedded artifact MUST appear exactly once.

ValueRequirement and Cardinality are orthogonal. ValueRequirement governs whether the user is obligated to supply any values at all. Cardinality governs the permitted count of values if any are supplied. A field may therefore be Optional — meaning the user is not required to fill it in — while carrying a min_cardinality greater than one, meaning that if values are supplied, at least that many must be present. For example, a primer pair field might be Optional but carry min_cardinality(2), because a primer pair is only interpretable when both the forward and reverse primers are specified together.

Visibility

Visibility determines whether the embedded artifact is shown in rendered interfaces. It is modeled as an embedding property rather than as a rendering hint because it applies to any kind of embedded artifact, not only to fields.

Visibility ::= "visible" | "hidden"

When Visibility is absent from an EmbeddedArtifact, the default is "visible".

Defaults

A default value is a value used to pre-populate a field at instance-creation time when no explicit value has yet been supplied by the user. Defaults exist at two layers:

• A field-level default lives on the reusable Field’s FieldSpec. It is set when the field is authored and is shared by every Template that embeds the field.
• An embedding-level default lives on the EmbeddedXxxField inside a Template. It overrides the field-level default for embeddings within that one Template.

Every concrete field family carries an optional default at both layers, with one exception: AttributeValueField carries no default at either layer (an AttributeValue instance is a per-instance pairing of an attribute name and a value, and a default is not meaningful).

The two default-value types match: at each layer the slot is typed with the family-specific Value type. The per-family typing is:

The shape is uniform across layers: every default at every layer is the family’s Value type. For the enum families this means the field-level default is an EnumValue (or sequence of EnumValue) — the same kind-tagged object form that appears at the embedding level. The Token carried inside each default EnumValue MUST equal the Token of one of the spec’s PermissibleValue+ entries; for MultiValuedEnumFieldSpec the sequence MUST NOT contain duplicate tokens.

Precedence and absence semantics. Both layers are independent and optional. The four cases:

There is no mechanism for an embedding to unset a field-level default. An embedding that wishes to override a field-level default with no default at all is not expressible in this version of the model.

Defaults are UI/UX initialisation only. A default value’s sole role is to seed an instance’s value at creation time, so that a user-facing form can pre-fill the corresponding input. Defaults do not appear in the wire form of TemplateInstance artifacts and do not affect the RDF projection. When an instance is created and the user accepts the default without modification, the resulting FieldValue carries the default value as if the user had typed it in by hand; from the instance’s perspective the default and a user-supplied identical value are indistinguishable. When an instance is created and the user does not supply a value (and the field is not required), the corresponding FieldValue is omitted entirely — the default does not appear by virtue of having existed.

Label Override

LabelOverride provides template-specific labeling for an embedded artifact. This allows a template to override the default label of the referenced reusable artifact in that embedding context.

AlternativeLabel ::= alternative_label(
                       MultilingualString
                     )

LabelOverride ::= label_override(
                    Label
                    AlternativeLabel*
                  )

AlternativeLabel is a MultilingualString: each entry is itself a localization set for one alternative phrasing of the artifact’s display label.

Help Text Override

HelpTextOverride provides template-specific authored guidance for an embedded field. When present, it replaces the field’s canonical HelpText for that embedding context only. The reusable Field’s HelpText remains the canonical content for all other embedding contexts (and for the field rendered standalone).

HelpTextOverride ::= help_text_override( MultilingualString )

HelpTextOverride is a MultilingualString: it carries the same kind of authored guidance as HelpText, but scoped to a single embedding site. The override’s presentation — inline, tooltip, both, or none — is selected by the enclosing Template’s HelpDisplayMode exactly as for the underlying HelpText.

The precedence rule is straightforward: at an embedding site, the renderer displays the embedding’s HelpTextOverride if present, otherwise the referenced Field’s HelpText, otherwise nothing. The override is replace, not merge: localizations present in the field’s HelpText but absent from the embedding’s HelpTextOverride do not fall back.

Properties

A Property associates a semantic property IRI with an EmbeddedField or EmbeddedTemplate within a specific Template. The property IRI identifies the RDF property that the embedded artifact’s value represents in that template context. The optional PropertyLabel provides a human-readable label for the property.

Property is an embedding-level construct. It is distinct from the intrinsic metadata of the referenced Field or Template artifact. The same reusable artifact may be embedded in different templates under different property IRIs.

Property ::= property(
               PropertyIri
               [PropertyLabel]
             )

PropertyIri   ::= property_iri( Iri )
PropertyLabel ::= property_label( MultilingualString )

PropertyLabel is a MultilingualString carrying one or more language-tagged localizations of the property’s human-readable label.

Field Specs

A FieldSpec is the semantic configuration block carried by a concrete Field artifact. It specifies what kind of value the field accepts, any constraints on that value, and any compatible rendering hints for presentation. Each concrete Field variant carries exactly one FieldSpec that matches its kind: a TextField carries a TextFieldSpec, a DateField carries a DateFieldSpec, and so on. The correspondence between each FieldSpec and its permitted Value form is given in the Field Spec And Value Correspondence section.

One might ask why FieldSpec exists as a separate construct rather than folding its content directly into the concrete Field artifact. The answer is separation of concerns: the concrete field artifact — TextField, DateField, and so on — answers the question “what kind of reusable field is this?” and carries the artifact’s identity, catalog metadata, versioning, and the rendered question-text label. The FieldSpec answers the separate question “what are the value rules and rendering-compatible properties for this kind of field?” Keeping these concerns distinct means that artifact identity, catalog metadata, and lifecycle/versioning information remain uniform across all field kinds, while value semantics and field-specific configuration vary per family through FieldSpec.

FieldSpec productions are grouped here by field family, mirroring the abstract Field hierarchy in the Kernel Grammar. Temporal field specs, which carry additional precision and rendering configuration, are detailed in the Temporal Field Specs subsection. Controlled term source declarations, which specify the ontological authorities from which controlled-term values may be drawn, are covered in the Controlled Term Sources subsection. Rendering hints for all field families are defined in the Rendering Hints subsection, with the exception of temporal rendering hints which are defined alongside their field specs.

FieldSpec ::= TextFieldSpec
            | NumericFieldSpec
            | BooleanFieldSpec
            | TemporalFieldSpec
            | ControlledTermFieldSpec
            | EnumFieldSpec
            | LinkFieldSpec
            | ContactFieldSpec
            | ExternalAuthorityFieldSpec
            | AttributeValueFieldSpec

NumericFieldSpec ::= IntegerNumberFieldSpec
                   | RealNumberFieldSpec

TextFieldSpec ::= text_field_spec(
                    [TextValue]
                    [MinLength]
                    [MaxLength]
                    [ValidationRegex]
                    [LangTagRequirement]
                    [TextRenderingHint]
                  )

LangTagRequirement ::= "langTagRequired"
                     | "langTagOptional"
                     | "langTagForbidden"

IntegerNumberFieldSpec ::= integer_number_field_spec(
                             [IntegerNumberValue]
                             [Unit]
                             [IntegerNumberMinValue]
                             [IntegerNumberMaxValue]
                             [NumericRenderingHint]
                           )

RealNumberFieldSpec ::= real_number_field_spec(
                          RealNumberDatatypeKind
                          [RealNumberValue]
                          [Unit]
                          [RealNumberMinValue]
                          [RealNumberMaxValue]
                          [NumericRenderingHint]
                        )

Unit ::= unit(
           Iri
           [Label]
         )

MinLength ::= min_length(
                NonNegativeInteger
              )

MaxLength ::= max_length(
                NonNegativeInteger
              )

ValidationRegex ::= validation_regex(
                      string
                    )

IntegerNumberMinValue ::= integer_number_min_value(
                            IntegerNumberValue
                          )

IntegerNumberMaxValue ::= integer_number_max_value(
                            IntegerNumberValue
                          )

RealNumberMinValue ::= real_number_min_value(
                         RealNumberValue
                       )

RealNumberMaxValue ::= real_number_max_value(
                         RealNumberValue
                       )

BooleanFieldSpec ::= boolean_field_spec(
                       [BooleanValue]
                       [BooleanRenderingHint]
                     )

TemporalFieldSpec ::= DateFieldSpec
                    | TimeFieldSpec
                    | DateTimeFieldSpec

ControlledTermFieldSpec ::= controlled_term_field_spec(
                              [ControlledTermValue]
                              ControlledTermSource+
                              [ControlledTermRenderingHint]
                            )

EnumFieldSpec ::= SingleValuedEnumFieldSpec
                | MultiValuedEnumFieldSpec

SingleValuedEnumFieldSpec ::= single_valued_enum_field_spec(
                                PermissibleValue+
                                [EnumValue]
                                [SingleValuedEnumRenderingHint]
                              )

MultiValuedEnumFieldSpec ::= multi_valued_enum_field_spec(
                               PermissibleValue+
                               EnumValue*
                               [MultiValuedEnumRenderingHint]
                             )

PermissibleValue ::= permissible_value(
                       Token
                       [Label]
                       [Description]
                       Meaning*
                     )

Token ::= token(
            string
          )

Meaning ::= meaning(
              TermIri
              [Label]
            )

LinkFieldSpec ::= link_field_spec(
                    [LinkValue]
                    [LinkRenderingHint]
                  )

ContactFieldSpec ::= EmailFieldSpec
                   | PhoneNumberFieldSpec

EmailFieldSpec ::= email_field_spec(
                     [EmailValue]
                     [EmailRenderingHint]
                   )

PhoneNumberFieldSpec ::= phone_number_field_spec(
                           [PhoneNumberValue]
                           [PhoneNumberRenderingHint]
                         )

ExternalAuthorityFieldSpec ::= OrcidFieldSpec
                             | RorFieldSpec
                             | DoiFieldSpec
                             | PubMedIdFieldSpec
                             | RridFieldSpec
                             | NihGrantIdFieldSpec

OrcidFieldSpec ::= orcid_field_spec(
                     [OrcidValue]
                     [OrcidRenderingHint]
                   )

RorFieldSpec ::= ror_field_spec(
                   [RorValue]
                   [RorRenderingHint]
                 )

DoiFieldSpec ::= doi_field_spec(
                   [DoiValue]
                   [DoiRenderingHint]
                 )

PubMedIdFieldSpec ::= pub_med_id_field_spec(
                        [PubMedIdValue]
                        [PubMedIdRenderingHint]
                      )

RridFieldSpec ::= rrid_field_spec(
                    [RridValue]
                    [RridRenderingHint]
                  )

NihGrantIdFieldSpec ::= nih_grant_id_field_spec(
                          [NihGrantIdValue]
                          [NihGrantIdRenderingHint]
                        )

AttributeValueFieldSpec ::= attribute_value_field_spec()

Unit denotes an identified measurement or quantity unit optionally paired with a human-readable label.

The current placement of Unit on IntegerNumberFieldSpec and RealNumberFieldSpec is a pragmatic compromise. A later revision may introduce a distinct QuantityFieldSpec to model numeric values with fixed units more explicitly.

IntegerNumberMinValue and IntegerNumberMaxValue specify inclusive lower and upper bounds on the integer values that an IntegerNumberField accepts. Both are expressed as IntegerNumberValue constructs. RealNumberMinValue and RealNumberMaxValue are the analogous bounds on RealNumberField and carry RealNumberValue constructs whose RealNumberDatatypeKind matches the field’s declared datatype.

A RealNumberFieldSpec MAY use the family-shared NumericRenderingHint; if it carries a non-zero decimalPlaces rendering hint, the hint applies to display rounding only and does not constrain the lexical form of submitted values. IntegerNumberFieldSpec MAY also use NumericRenderingHint; a decimalPlaces value other than 0 on an integer field is harmless (display only) and SHOULD be omitted when not meaningful.

EnumFieldSpec is refined along a single dimension: cardinality. SingleValuedEnumFieldSpec permits exactly one selection; MultiValuedEnumFieldSpec permits zero or more simultaneous selections (subject to the embedding’s Cardinality). The two specs share a common option model: every permissible value is a PermissibleValue carrying a canonical Token key together with optional human-readable Label and Description localizations and zero or more Meaning entries that bind the token to ontology terms. The Token strings of a spec’s permissible values MUST be unique within that spec; the spec’s PermissibleValue+ is the closed set of values an instance may carry.

The two enum specs each carry a field-level default per the Defaults section: SingleValuedEnumFieldSpec an optional [EnumValue], MultiValuedEnumFieldSpec a (possibly empty) EnumValue*. The Token carried inside each default EnumValue MUST equal the Token of one of the spec’s PermissibleValue+ entries; for MultiValuedEnumFieldSpec the sequence MUST NOT contain duplicate tokens.

A Meaning carried by a PermissibleValue binds the token to a term IRI in an external vocabulary or ontology. A permissible value MAY carry zero, one, or several Meaning entries. Each Meaning MAY additionally carry an optional Label recording the bound term’s human-readable label (in the same way ControlledTermValue.Label caches the term’s label inline) so that consumers without ontology access can render the bound term’s display name. The Meaning.Label is the label of the bound term, distinct from the surrounding PermissibleValue.Label which is the display label of the permissible value itself. When the RDF projection is applied (see rdf-projection.md), an EnumValue whose token matches a PermissibleValue carrying one or more Meaning entries projects as the corresponding term IRIs; an EnumValue whose matching permissible value carries no Meaning projects as a plain string literal.

ControlledTermSource is defined in Controlled Term Sources.

Temporal Field Specs

TemporalFieldSpec denotes temporal-valued fields and is refined into strongly typed date, time, and date-time forms. This section groups the temporal field-spec productions together with their compatible rendering hints and value-type constraints.

DateFieldSpec ::= date_field_spec(
                    DateValueType
                    [DateValue]
                    [DateRenderingHint]
                  )

DateValueType ::= "year" | "yearMonth" | "fullDate"

TimeFieldSpec ::= time_field_spec(
                    [TimeValue]
                    [TimePrecision]
                    [TimezoneRequirement]
                    [TimeRenderingHint]
                  )

TimePrecision ::= "hourMinute" | "hourMinuteSecond" | "hourMinuteSecondFraction"

TimezoneRequirement ::= "timezoneRequired" | "timezoneNotRequired"

TimePrecision identifies the finest time precision permitted by a TimeFieldSpec.

"hourMinute", "hourMinuteSecond", and "hourMinuteSecondFraction" identify time values constrained respectively to hour-and-minute precision, second precision, and fractional-second precision.

TimezoneRequirement identifies whether timezone information is required by the field spec.

The declared TimePrecision determines the required lexical form of conforming TimeValue constructs. Finer components than the declared precision MUST be omitted entirely; zeroing them is not equivalent to omitting them. Specifically:

• "hourMinute": TimeValue MUST carry only hour and minute components (HH:MM).
• "hourMinuteSecond": TimeValue MUST carry hour, minute, and second components (HH:MM:SS), with no fractional seconds.
• "hourMinuteSecondFraction": TimeValue MAY carry a fractional seconds component.

When TimePrecision is absent from a TimeFieldSpec, no precision constraint applies and any well-formed TimeValue is conforming.

The same strict-truncation rule applies to DateTimeValueType for DateTimeValue constructs:

• "dateHourMinute": the time component of DateTimeValue MUST carry only hour and minute (YYYY-MM-DDTHH:MM).
• "dateHourMinuteSecond": the time component MUST carry hour, minute, and second (YYYY-MM-DDTHH:MM:SS), with no fractional seconds.
• "dateHourMinuteSecondFraction": the time component MAY carry a fractional seconds component.

DateTimeFieldSpec ::= date_time_field_spec(
                        DateTimeValueType
                        [DateTimeValue]
                        [TimezoneRequirement]
                        [DateTimeRenderingHint]
                      )

DateTimeValueType ::= "dateHourMinute" | "dateHourMinuteSecond" | "dateHourMinuteSecondFraction"

DateTimeValueType identifies the finest permitted date-time precision.

"dateHourMinute", "dateHourMinuteSecond", and "dateHourMinuteSecondFraction" identify date-time values constrained respectively to minute precision, second precision, and fractional-second precision.

DateRenderingHint ::= date_rendering_hint(
                        [DateComponentOrder]
                        [Placeholder]
                      )

DateComponentOrder ::= "dayMonthYear" | "monthDayYear" | "yearMonthDay"

TimeRenderingHint ::= time_rendering_hint(
                        [TimeFormat]
                        [Placeholder]
                      )

DateTimeRenderingHint ::= date_time_rendering_hint(
                            [TimeFormat]
                            [Placeholder]
                          )

TimeFormat ::= "twelveHour" | "twentyFourHour"

DateComponentOrder identifies whether a date is rendered or acquired in day-month-year, month-day-year, or year-month-day order.

Controlled Term Sources

Controlled term sources define the ontological authorities from which controlled-term values may be drawn. A ControlledTermFieldSpec requires one or more ControlledTermSource entries. Each source specifies either an entire ontology, a branch of an ontology rooted at a given term, a set of individual ontology classes, or an external value set. TermIri is defined in the Scalar and Datatype Leaves section.

ControlledTermSource ::= OntologySource
                       | BranchSource
                       | ClassSource
                       | ValueSetSource

OntologySource ::= ontology_source(
                     OntologyReference
                   )

OntologyReference ::= ontology_reference(
                        OntologyIri
                        [OntologyDisplayHint]
                      )

OntologyDisplayHint ::= ontology_display_hint(
                          [OntologyAcronym]
                          [OntologyName]
                        )

BranchSource ::= branch_source(
                   OntologyReference
                   RootTermIri
                   [RootTermLabel]
                   [MaxTraversalDepth]
                 )

ClassSource ::= class_source(
                  ControlledTermClass+
                )

ControlledTermClass ::= controlled_term_class(
                          TermIri
                          [Label]
                          OntologyReference
                        )

ValueSetSource ::= value_set_source(
                     ValueSetIdentifier
                     [ValueSetName]
                     [ValueSetIri]
                   )

OntologyAcronym ::= ontology_acronym(
                      string
                    )

OntologyName ::= ontology_name(
                   MultilingualString
                 )

OntologyIri ::= ontology_iri(
                  Iri
                )

RootTermIri ::= root_term_iri(
                  Iri
                )

RootTermLabel ::= root_term_label(
                    MultilingualString
                  )

MaxTraversalDepth ::= max_traversal_depth(
                        NonNegativeInteger
                      )

ValueSetIdentifier ::= value_set_identifier(
                         string
                       )

ValueSetName ::= value_set_name(
                   MultilingualString
                 )

ValueSetIri ::= value_set_iri(
                  Iri
                )

OntologyIri, RootTermIri, and ValueSetIri denote IRIs used in controlled-term source specifications.

OntologyName, RootTermLabel, and ValueSetName are human-readable display names and carry MultilingualString values: each may be presented in one or more natural languages. OntologyAcronym and ValueSetIdentifier are technical short-form identifiers (e.g. an ontology acronym like "NCIT", a value-set key) and remain plain Unicode strings.

MaxTraversalDepth denotes a non-negative traversal-depth limit for branch-based controlled-term sources. When MaxTraversalDepth is absent, no depth limit applies and any descendant of the root term is admissible. A value of zero restricts the source to the root term itself.

When OntologyDisplayHint is present on an OntologyReference, at least one of its OntologyAcronym or OntologyName components MUST be present. A display hint with neither component is non-conforming.

A ControlledTermClass SHOULD include a Label. The label is captured at the time the class is declared as a source, when the term’s display text is typically known; consumers without ontology access rely on this label to render the class. Conforming producers MAY omit the label when it is not available, in which case downstream consumers must resolve the label from the term IRI by other means. The same recommendation applies to BranchSource.RootTermLabel: producers SHOULD include it when declaring a branch source.

Rendering Hints

A RenderingHint is an optional presentational instruction carried by a FieldSpec that tells a rendering implementation how to display the field. Rendering hints are strictly presentational: they do not affect the meaning, structure, or validation of field values. Each rendering hint is typed to a specific FieldSpec family, so only compatible hint-and-field-spec combinations are expressible. For example, a TextRenderingHint may only appear on a TextFieldSpec, and a SingleValuedEnumRenderingHint may only appear on a SingleValuedEnumFieldSpec. Note that temporal rendering hints (DateRenderingHint, TimeRenderingHint, and DateTimeRenderingHint) are defined alongside their respective field specs in the Temporal Field Specs subsection.

RenderingHint ::= TextRenderingHint
                | SingleValuedEnumRenderingHint
                | MultiValuedEnumRenderingHint
                | NumericRenderingHint
                | BooleanRenderingHint
                | DateRenderingHint
                | TimeRenderingHint
                | DateTimeRenderingHint
                | ControlledTermRenderingHint
                | EmailRenderingHint
                | PhoneNumberRenderingHint
                | LinkRenderingHint
                | OrcidRenderingHint
                | RorRenderingHint
                | DoiRenderingHint
                | PubMedIdRenderingHint
                | RridRenderingHint
                | NihGrantIdRenderingHint

TextRenderingHint ::= text_rendering_hint(
                        [TextLineMode]
                        [Placeholder]
                      )

TextLineMode ::= "singleLine" | "multiLine"

SingleValuedEnumRenderingHint ::= "radio" | "dropdown"

MultiValuedEnumRenderingHint ::= "checkbox" | "multiSelect"

NumericRenderingHint ::= numeric_rendering_hint(
                           [DecimalPlaces]
                           [Placeholder]
                         )

DecimalPlaces ::= decimal_places(
                    NonNegativeInteger
                  )

BooleanRenderingHint ::= "checkbox" | "toggle" | "radio" | "dropdown"

ControlledTermRenderingHint ::= controlled_term_rendering_hint( [Placeholder] )
EmailRenderingHint          ::= email_rendering_hint(            [Placeholder] )
PhoneNumberRenderingHint    ::= phone_number_rendering_hint(     [Placeholder] )
LinkRenderingHint           ::= link_rendering_hint(             [Placeholder] )
OrcidRenderingHint          ::= orcid_rendering_hint(            [Placeholder] )
RorRenderingHint            ::= ror_rendering_hint(              [Placeholder] )
DoiRenderingHint            ::= doi_rendering_hint(              [Placeholder] )
PubMedIdRenderingHint       ::= pub_med_id_rendering_hint(       [Placeholder] )
RridRenderingHint           ::= rrid_rendering_hint(             [Placeholder] )
NihGrantIdRenderingHint     ::= nih_grant_id_rendering_hint(     [Placeholder] )

Placeholder ::= placeholder( MultilingualString )

Placeholder is a MultilingualString-valued production carrying sample-input text shown inside an empty text-entry widget. It is purely presentational format demonstration — distinct from HelpText, which carries semantic content about the field’s meaning. Placeholder content is not validated against the field spec’s lexical-form constraints; a placeholder of "YYYY-MM-DD" may appear on a date field whose values must conform to ISO 8601, since the placeholder is a demonstration of the expected lexical shape, not an instance of one.

Placeholder appears as an optional slot on every rendering hint attached to a text-entry-capable field family: TextRenderingHint, NumericRenderingHint, DateRenderingHint, TimeRenderingHint, DateTimeRenderingHint, plus the ten rendering hints introduced for ControlledTermField, EmailField, PhoneNumberField, LinkField, and the six identifier families. It does NOT appear on BooleanRenderingHint, SingleValuedEnumRenderingHint, or MultiValuedEnumRenderingHint, since those widgets are not text-entry surfaces.

Note on TextRenderingHint shape. In earlier revisions of this spec, TextRenderingHint was a bare string enum ("singleLine" | "multiLine"). It has been restructured into a structured object carrying an optional TextLineMode (the former enum content) plus the optional Placeholder slot. This is a wire-form-breaking change for templates that carry the bare-string form; such templates require migration to the object form before they will decode under this revision of the spec.

This specification draws a strict distinction between semantic structure and presentation. Semantic distinctions MUST be modeled in FieldSpec when they affect the meaning, cardinality, or value structure of a field. This includes distinctions such as single-valued versus multi-valued enum, date versus time versus date-time, and permitted temporal precision. Purely presentational distinctions MUST NOT be modeled as separate field specs. Instead, distinctions such as single-line versus multi-line text entry, date component ordering, and 12-hour versus 24-hour time display MUST be expressed only through compatible typed rendering hints.

Accordingly, TextFieldSpec is a single semantic field spec whose single-line and multi-line display forms are represented by TextRenderingHint.

A TextFieldSpec MAY additionally define a default text value, minimum length, maximum length, validating regular expression, and a LangTagRequirement constraining the presence of the lang slot on conforming TextValue instances.

LangTagRequirement identifies whether the lang slot of a TextValue is required, optional, or forbidden by the field spec:

• "langTagRequired" — every TextValue admitted by this field MUST carry a lang slot with a well-formed BCP 47 tag. Suitable for fields whose values are natural-language text that authors expect to be language-tagged (e.g., titles, abstracts, captions).
• "langTagOptional" — every TextValue admitted MAY carry a lang slot. This matches the default behaviour when LangTagRequirement is absent and is provided for explicitness.
• "langTagForbidden" — every TextValue admitted MUST NOT carry a lang slot. Suitable for fields whose values are technical identifiers, slugs, query fragments, or other strings for which a natural-language tag has no meaning.

When LangTagRequirement is absent from a TextFieldSpec, the constraint behaves as "langTagOptional" (the historical default).

The LangTagRequirement constraint applies to each TextValue individually: in a multi-valued field, every value MUST satisfy the constraint independently. The constraint also applies to the field-spec-level defaultValue (when present) and to any embedding-level defaultValue carried by an EmbeddedTextField.

Similarly, EnumFieldSpec distinguishes SingleValuedEnumFieldSpec from MultiValuedEnumFieldSpec semantically, while the rendering hint determines whether the UI uses radio buttons, dropdown, checkboxes, or multi-select presentation. Typed rendering hints make incompatible combinations structurally invalid.

Temporal semantics are also split structurally: DateFieldSpec, TimeFieldSpec, and DateTimeFieldSpec are distinct semantic field specs, and each carries only the rendering hints and temporal options that are meaningful for that temporal category.

The current rendering vocabulary is explicit but deliberately small: numeric fields use NumericRenderingHint (which carries an optional DecimalPlaces for display-time rounding); date fields use DateRenderingHint (with optional DateComponentOrder); time fields use TimeRenderingHint (with optional TimeFormat); and date-time fields use DateTimeRenderingHint (also with optional TimeFormat).

DecimalPlaces is a presentation concern, not a value-semantics constraint. Conforming consumers SHOULD use it to control display rounding and MAY use it as a UX-level input nicety (e.g., limiting the number of digits an end-user can type after the decimal point). It does not constrain the lexical form of a submitted RealNumberValue; conforming validators MUST NOT reject a value purely on grounds of decimal-places mismatch with the rendering hint. The slot is meaningful for RealNumberFieldSpec; on IntegerNumberFieldSpec it is harmless and conventionally omitted.

BooleanRenderingHint admits four widget choices — checkbox, toggle, radio, and dropdown — distinguished by how they handle the unset state of a boolean field. A boolean field has three observable states at the UI: a value of true, a value of false, and no value supplied (the user has not yet asserted either). The four widget choices differ in whether they can faithfully represent the unset state:

• radio (a Yes / No radio pair) and dropdown (a Yes / No dropdown with no initial selection) admit three observable states — Yes selected, No selected, and neither selected — and so faithfully represent the unset case.
• checkbox and toggle admit only two observable states (checked / unchecked, or on / off) and so cannot distinguish false from unset. They SHOULD be used only when the field’s ValueRequirement is required (so unset is not a valid resting state) or when the surrounding application is content to interpret unset as false.

The unset state is structurally represented in the value model by absence of a FieldValue for the embedding’s key, not by a third value within BooleanValue. BooleanValue.value carries true | false only.

Presentation Components

A PresentationComponent is a reusable artifact that contributes presentation or instructional structure to a rendered template without introducing data-bearing content. It is distinct from SchemaArtifact: where Template and Field define the structure and semantics of instance data, PresentationComponent exists purely to guide, organise, or annotate the rendered form — for example by embedding rich text instructions, illustrative images, video content, or structural breaks between sections.

PresentationComponent carries its own identity, metadata, and lifecycle information as an Artifact, making it independently reusable across multiple templates. It appears within a template only through EmbeddedPresentationComponent, which contributes no InstanceValue and is therefore invisible to the instance model. A conforming TemplateInstance MUST NOT contain an InstanceValue for an EmbeddedPresentationComponent.

The following concrete variants are defined:

PresentationComponent ::= RichTextComponent
                        | ImageComponent
                        | YoutubeVideoComponent
                        | SectionBreakComponent
                        | PageBreakComponent

RichTextComponent ::= rich_text_component(
                        PresentationComponentId
                        ModelVersion
                        CatalogMetadata
                        HtmlContent
                      )

ImageComponent ::= image_component(
                     PresentationComponentId
                     ModelVersion
                     CatalogMetadata
                     Iri
                     [Label]
                     [Description]
                   )

YoutubeVideoComponent ::= you_tube_video_component(
                            PresentationComponentId
                            ModelVersion
                            CatalogMetadata
                            Iri
                            [Label]
                            [Description]
                          )

SectionBreakComponent ::= section_break_component(
                            PresentationComponentId
                            ModelVersion
                            CatalogMetadata
                          )

PageBreakComponent ::= page_break_component(
                         PresentationComponentId
                         ModelVersion
                         CatalogMetadata
                       )

HtmlContent ::= html_content(
                  string
                )

HtmlContent denotes an HTML fragment represented as a Unicode string and used by a RichTextComponent.

The permitted HTML feature set and any sanitization requirements are outside the scope of this abstract specification and SHOULD be defined by concrete serialization specifications that build on this model.

The Iri slot on ImageComponent and YoutubeVideoComponent identifies the image or video resource referenced by the corresponding presentation component.

Label and Description on ImageComponent and YoutubeVideoComponent carry accessibility metadata. Label is a short alternative-text label (the image’s alt text or the video’s caption title); Description is a longer textual description for screen readers and other assistive technologies. Both are MultilingualString values, allowing localized accessibility text. Conforming producers SHOULD provide a Label for every ImageComponent and YoutubeVideoComponent that conveys meaningful content; decorative images MAY omit the label to indicate that no alternative text is needed.

Field Spec And Value Correspondence

The FieldSpec carried by a Field determines the Value form that MUST appear in any FieldValue corresponding to an embedding of that field. This is a normative constraint: a FieldValue that carries a Value of the wrong form for the referenced field’s FieldSpec is non-conforming.

The correspondence is applied through the EmbeddedArtifactKey chain. A FieldValue in a TemplateInstance carries an EmbeddedArtifactKey that identifies an EmbeddedField in the referenced Template. That EmbeddedField references a reusable Field, which carries a FieldSpec. It is that FieldSpec that determines the permitted Value form for the FieldValue. The correspondence therefore spans the full path from instance value through embedding context to reusable field definition.

The table below gives the complete correspondence. The Field Family column identifies the abstract category in the Field hierarchy to which the concrete field belongs; families group field kinds that share related value semantics. Where a field is a direct subclass of Field with no intermediate abstract category, this column is left blank.

The two concrete enum field specs share a single value type, EnumValue. The cardinality distinction — single versus multiple — is not visible in the value type itself but in the count of values permitted per FieldValue: a SingleValuedEnumFieldSpec permits exactly one EnumValue, while a MultiValuedEnumFieldSpec permits one or more (subject to the embedding’s Cardinality). This cardinality constraint is enforced at validation rather than through distinct value types.

Instances

A TemplateInstance is an Artifact that records data conforming to a specific Template. Instance productions are defined here separately from schema and presentation productions so that the schema model and the instance model can be read independently.

Because TemplateInstance is a full Artifact, it carries CatalogMetadata — a TemplateInstanceId, descriptive metadata, and lifecycle metadata. This means instances are independently identifiable, catalogable artifacts in their own right rather than anonymous data records. They can be referenced, versioned, and tracked just as templates and fields can.

A TemplateInstance contains zero or more InstanceValue constructs, each keyed by an EmbeddedArtifactKey identifying the corresponding embedded artifact in the referenced template. There are two forms: FieldValue, which carries one or more typed values for an EmbeddedField, and NestedTemplateInstance, which carries a nested collection of InstanceValue constructs for an EmbeddedTemplate. EmbeddedPresentationComponent constructs produce no InstanceValue and are absent from the instance model entirely.

TemplateInstance ::= template_instance(
                       TemplateInstanceId
                       ModelVersion
                       CatalogMetadata
                       TemplateId
                       [Label]
                       InstanceValue*
                     )

InstanceValue ::= FieldValue
                | NestedTemplateInstance

FieldValue ::= field_value(
                 EmbeddedArtifactKey
                 Value+
               )

NestedTemplateInstance ::= nested_template_instance(
                             EmbeddedArtifactKey
                             InstanceValue*
                           )

TemplateId is the persistent schema link that ties a TemplateInstance to the Template it was created from. It is the basis for all validation and interpretation of instance content: the EmbeddedArtifactKey values in FieldValue and NestedTemplateInstance constructs are only meaningful in relation to the embedded artifacts of that specific template.

Each FieldValue’s EmbeddedArtifactKey MUST identify an EmbeddedField in the referenced Template. Each NestedTemplateInstance’s EmbeddedArtifactKey MUST identify an EmbeddedTemplate. An EmbeddedArtifactKey that identifies an EmbeddedPresentationComponent MUST NOT appear as the key of any InstanceValue. The full instance alignment constraints are specified in spec/validation.md.

To make the abstract structure concrete, consider a Template containing two EmbeddedTextField constructs keyed title and description, and one EmbeddedTemplate keyed study_arm with a maximum cardinality of three. A conforming TemplateInstance for that template would contain two FieldValue constructs — one keyed title carrying a TextValue, one keyed description carrying a TextValue — and between one and three NestedTemplateInstance constructs each keyed study_arm, where each NestedTemplateInstance contains its own InstanceValue constructs corresponding to the embedded artifacts of the nested template.

For multi-valued EmbeddedField, all values for a single field occurrence are collected within a single FieldValue using Value*. For multi-valued EmbeddedTemplate, multiplicity is represented by multiple NestedTemplateInstance constructs sharing the same EmbeddedArtifactKey within the containing TemplateInstance. This asymmetry reflects the structural difference between scalar repetition (multiple values for one field) and structural repetition (multiple complete nested instances for one embedded template). In both cases the number of values or instances MUST satisfy the Cardinality constraints defined by the corresponding EmbeddedField or EmbeddedTemplate; see spec/validation.md for the normative multiplicity rules. NestedTemplateInstance is the recursive construct that supports arbitrarily deep nested template structure: because a NestedTemplateInstance itself contains InstanceValue*, and InstanceValue may contain further NestedTemplateInstance constructs, template nesting can be as deep as the schema requires.

Instance conformance may be enforced at data-entry time, preventing submission of a non-conforming instance, or retrospectively, by validating existing instances against their referenced template. Both modes apply the same conformance rules; the distinction is an implementation concern rather than a model-level distinction.

Absence of a value for an optional field is represented by omitting the FieldValue entirely rather than including an empty one; hence FieldValue requires Value+. Note that concrete serializations and authoring tools may have their own conventions for representing absence — for example, a JSON serialization may choose to omit a key entirely or include it with a null value — but such distinctions are a concern of the serialization layer and do not affect the abstract model defined here.

Open Questions

• Should embedded artifacts always refer to reusable artifacts by explicit reference construct, or does the CEDAR model require some embeddings to support inline artifact definition?
• Should PresentationComponent remain a direct subclass of Artifact, or should a later revision introduce an intermediate superclass for reusable non-schema artifacts? This would make the distinction between reusable schema artifacts such as Template and Field and reusable non-schema artifacts such as rich text, images, videos, and section breaks more explicit in the hierarchy.
• Should a later revision introduce a distinct QuantityFieldSpec rather than attaching optional Unit information directly to IntegerNumberFieldSpec and RealNumberFieldSpec? The current model permits fixed units on both numeric field families as a pragmatic compromise, but a dedicated quantity field spec may provide a cleaner semantic distinction for numeric values that are intrinsically unit-bearing.

Cedar Wire Grammar

This file is a formal, JSON-shaped grammar that mirrors grammar.md production-for-production. It is the source of truth for the wire shape of every abstract grammar production. serialization.md is its companion: it carries the encoding philosophy, JSON-specific rules (property naming, NFC normalisation, etc.), worked examples, and cross-references, but does not duplicate per-production shape information.

For every XxxYyy ::= in grammar.md there is exactly one XxxYyy ::: in this file, and vice versa.

Status: hand-maintained, eventually generated. This file is currently authored in lock-step with grammar.md. The longer-term direction is to derive it mechanically from grammar.md plus the property-name map (§14) plus the encoding rules (§1.7). Until that generator exists, the file is hand-maintained; the §14 property-name map and the §1.7 encoding rules together define what such a generator would need to know.

1. Notation

Each line takes one of two forms:

production_name ::: type-expression
production_name ::: type-expression
  // inline constraints on this production

(The placeholder production_name is shown in lower_snake_case here purely to keep it out of the formal-production count; real wire productions use UpperCamelCase.) The ::: separator (three colons) distinguishes a wire-format production from an abstract grammar production (::= in grammar.md). A wire production names the JSON shape that encodes the corresponding abstract production.

1.1 Type expressions

1.2 Object property syntax

Within object { … }:

property: Type        // required
property?: Type       // optional; encoded only when present
"property": "literal" // a fixed string-literal value (used for kind)

Property order in the notation is informational. JSON does not preserve key order, and conforming encoders MAY emit properties in any order unless an inline constraint says otherwise (no current production requires a specific order).

1.3 Unions

some_union ::: A | B | C
  // discriminator: kind

(Placeholder shown in lower_snake_case for the same reason as §1.1.)

Two discrimination strategies are recognised, declared inline:

• discriminator: kind — every member is an object production whose shape includes a kind: "MemberName" literal property. Decoders pick the variant by reading kind.
• discriminator: position — members are distinguished by the enclosing property name and the surrounding context, not by anything on the encoded object itself. Used at singleton positions where the abstract grammar admits exactly one production at the property.

If no discriminator is declared, kind is the default.

1.4 Inline constraints

Constraints that cannot be expressed in the type expression appear as single-line //-prefixed comments immediately below the production:

MultilingualString ::: nonEmptyArray<LangString>
  // lang tags MUST be unique within the array (case-folded)

Constraints are normative.

1.5 The kind rule

Rule. A wire object carries a "kind": "X" property if and only if its abstract grammar production is a member of some discriminator: kind union — regardless of the position the object occupies in the wire form. Productions that are not members of any discriminator: kind union (Cardinality, Annotation, LabelOverride, Property, CatalogMetadata, LifecycleMetadata, SchemaArtifactVersioning, Unit, OntologyReference, OntologyDisplayHint, ControlledTermClass, PermissibleValue, Meaning, and the temporal RenderingHint object variants) never carry kind.

This rule is purely a property of the production: it does not depend on where in the document the object appears. A given production either always carries kind on the wire or never does. In particular, singleton positions — slots where the enclosing context already fixes the family — make no difference to whether kind is carried; a polymorphic-union member retains its kind even when the slot’s type pins the family unambiguously. The kind is then redundant for decoding (the family is recoverable from the slot type) but is retained because uniformity of the rule is more valuable than the small wire-size saving.

Terms.

• Singleton position — a property slot in a wire object where the abstract grammar admits exactly one production (e.g. EmbeddedField.cardinality admits only Cardinality, EmbeddedTextField.defaultValue admits only TextValue).
• Singleton-only production — an abstract production that appears only at singleton positions and is never a member of a discriminator: kind union (e.g. Cardinality, Annotation, LabelOverride). Equivalently: the productions enumerated in the Rule above.

Worked examples. Two cases illustrate the rule.

Case 1 — polymorphic-union member always carries kind. TextValue is a member of the Value union (which uses discriminator: kind). At the polymorphic FieldValue.values[*] position the wire form is:

{ "kind": "TextValue", "value": "Hello", "lang": "en" }

At the singleton EmbeddedTextField.defaultValue position, where the enclosing EmbeddedTextField.kind already fixes the family, the wire form is the same:

{
  "kind": "EmbeddedTextField",
  "key": "comment",
  "artifactRef": "https://example.org/fields/comment",
  "defaultValue": { "kind": "TextValue", "value": "Initial", "lang": "en" }
}

The inner "kind": "TextValue" is structurally redundant at this slot but is retained because TextValue is a polymorphic-union member and the rule is uniform across positions.

Case 2 — singleton-only production never carries kind. Cardinality is not a member of any discriminator: kind union — it appears only at singleton positions (e.g. EmbeddedField.cardinality, EmbeddedTemplate.cardinality). Its wire form never carries kind:

{
  "kind": "EmbeddedTextField",
  "key": "alias",
  "artifactRef": "https://example.org/fields/alias",
  "cardinality": { "min": 0, "max": 3 }
}

Wire vs. in-memory. The kind rule constrains the wire form, not the in-memory form of any host-language binding. Bindings MAY carry synthetic kind (or any other) discriminator fields on their in-memory representations of singleton-only productions — e.g. Cardinality, Annotation — for runtime introspection, type-guard ergonomics, or debugging. Any such synthetic discriminator MUST be stripped before encoding and MUST NOT appear on the wire; the converse is also possible (a binding’s in-memory type may omit a kind it chooses to recover from context, provided the encoder restores it). (See bindings.md §2.1 for examples.)

1.6 Collapsed wrappers

A typed singleton wrapper is an abstract grammar production whose constructor form has exactly one component. The inner component may be a primitive lexical category (string, number, boolean), another typed singleton wrapper, or a composite production such as MultilingualString. For example:

Iri        ::= iri(IriString)
TemplateId ::= template_id(IriString)
Label      ::= label(MultilingualString)

In the abstract grammar these productions exist to give a value a role — Iri is a syntactically valid IRI, TemplateId is specifically the identifier of a template, Label is a label rather than an arbitrary multilingual string. The abstract grammar treats these roles as distinct types so that, e.g., a TemplateId cannot be substituted for a FieldId even though both reduce to a string at the wire level.

On the wire, however, this typed-role information is recovered from the surrounding context (the property name and the abstract grammar production at that slot). The wrapper therefore collapses to its inner type at encode time and disappears from the JSON, leaving only the inner value (a primitive, an array, or whichever shape the inner type encodes to). The wire grammar still names the wrapper production where the abstract grammar does, so that slot types in composite productions remain isomorphic to the abstract grammar’s component types — but the wrapper’s wire form ::: is the wire form of whatever it carries.

The wrappers fall into four groups by inner type:

• IRI-typed (string, syntactically valid IRI per RFC 3987): Iri, TermIri, every XxxFieldId, TemplateId, TemplateInstanceId, PresentationComponentId, PropertyIri, OrcidIri, RorIri, DoiIri, PubMedIri, RridIri, NihGrantIri, OntologyIri, RootTermIri, ValueSetIri, PreviousVersion, DerivedFrom, CreatedBy, ModifiedBy.
• Other strings (string): LanguageTag, LexicalForm, IsoDateTimeStamp, OntologyAcronym, ValueSetIdentifier, Notation, Identifier, AttributeName, HtmlContent, EmbeddedArtifactKey, ValidationRegex, Token, Version, ModelVersion, CreatedOn, ModifiedOn.
• Numbers: NonNegativeInteger, MinCardinality, MaxCardinality, MinLength, MaxLength, DecimalPlaces, MaxTraversalDepth.
• MultilingualString-typed (the inner type is itself a composite, encoded as a nonEmptyArray<LangString> per the MultilingualString wire production; the wrapper carries no additional wire shape): Name, Description, PreferredLabel, AlternativeLabel, Label, PropertyLabel, OntologyName, ValueSetName, RootTermLabel, Header, Footer.

Version and ModelVersion carry SemanticVersion 2.0.0 lexical strings. CreatedOn and ModifiedOn carry ISO 8601 date-time lexical strings. CreatedBy, ModifiedBy, PreviousVersion, and DerivedFrom carry IRIs.

1.7 Encoding rules

This section summarises the rules a generator would apply to derive wire-grammar.md from grammar.md plus the property-name map (§14). The rules are also the framing under which the file should be read: each ::: production in the rest of the file is what these rules produce when applied to the corresponding ::= production in grammar.md.

1. Production naming. Every abstract production XxxYyy ::= ... in grammar.md becomes a wire production XxxYyy ::: ... with the same name.

2. Object-form productions. A production that composes one or more named components encodes as object { ... } with property names drawn from the property-name map (§14). When such a production is a member of a kind-discriminated union, its object additionally carries "kind": "XxxYyy" (see rule 7).

3. Optional components. A grammar.md [X] component becomes an optional wire property prop?: X and is omitted from the JSON when absent.

4. Repeated components. A grammar.md X* becomes a wire array<X>; a grammar.md X+ becomes a wire nonEmptyArray<X>. Some sequence positions are encoded as omittable optional arrays per the wrapping principle of serialization.md §5 — altLabels?: array<AlternativeLabel> and annotations?: array<Annotation> on CatalogMetadata are SHOULD-omitted when empty, and the spec-level MultiValuedEnumFieldSpec.defaultValues is similarly optional. These exceptions are flagged at the production sites with inline constraints.

5. Collapsed wrappers. Productions whose abstract form is a single-component wrapper around a primitive collapse to that primitive on the wire (§1.6). Their ::: definitions remain in this file for completeness and for use as type names at slot positions in composite productions: every slot in an object { ... } is typed with the abstract grammar’s component name (e.g. key: EmbeddedArtifactKey rather than key: string). This makes the wire form’s slot types isomorphic to the abstract grammar’s component types, even where the encoding bottoms out at a JSON primitive.

6. Discriminator strategies. Two strategies are recognised, declared inline on the union: discriminator: kind (default) and discriminator: position. See §1.3.

7. The kind rule. A kind: "X" literal property appears on a wire object if and only if its production is a member of some discriminator: kind union, regardless of position. Productions not so used (Cardinality, Annotation, LabelOverride, Property, etc.) never carry kind. See §1.5 for the full statement.

8. Primitive bottom-out. Where the abstract grammar uses a bare primitive type (string, boolean, number) without a typed wrapper, the wire form uses that primitive directly (e.g. Cardinality.min: number, BooleanValue.value: boolean).

The wrapping principle that underlies rule 5 is given normatively in serialization.md §5; this section restates only the form in which it appears in the wire grammar.

2. Scalar and Datatype Leaves

The grammar’s primitive string types (SemanticVersion, IriString, Bcp47Tag, Iso8601DateTimeLexicalForm, AsciiIdentifier, IntegerLexicalForm) are abstract leaves with no ::= production; on the wire they all encode as string, with constraints noted at each site that uses them.

2.1 Core IRI and string types

Iri ::: string
  // a syntactically valid IRI per RFC 3987. At every position in the
  // model where the grammar uses Iri the wire form is a JSON string.

TermIri ::: Iri
  // a documented role; encodes as Iri

LanguageTag ::: string
  // a well-formed BCP 47 language tag

LexicalForm ::: string
  // a Unicode string; SHOULD be in Unicode Normalization Form C

IsoDateTimeStamp ::: string
  // an ISO 8601 date-time lexical form

NonNegativeInteger ::: number
  // a JSON number that is a non-negative integer
  // values exceeding 2^53 - 1 MUST be encoded as a string

2.2 Multilingual strings

LangString ::: object {
  value: string
  lang: string
}
  // lang MUST be a well-formed BCP 47 tag

MultilingualString ::: nonEmptyArray<LangString>
  // lang tags MUST be unique within the array (case-folded comparison)

2.3 Numeric datatype kind

RealNumberDatatypeKind ::: "decimal" | "float" | "double"
  // CEDAR-native enum naming the three real-number kinds.
  // The mapping to XSD datatype IRIs is defined separately in
  // rdf-projection.md and is out of scope for the wire form.

IntegerNumberValue is fixed to a single integer category and carries no datatype slot on the wire. Temporal Value variants (FullDateValue, TimeValue, DateTimeValue) likewise carry no datatype slot — the temporal category is fixed by the variant’s kind.

3. Values

Value ::: TextValue | NumericValue | BooleanValue
        | DateValue | TimeValue | DateTimeValue
        | ControlledTermValue | EnumValue | LinkValue
        | EmailValue | PhoneNumberValue | ExternalAuthorityValue
        | AttributeValue
  // discriminator: kind
  // NumericValue, DateValue, and ExternalAuthorityValue are themselves
  // unions; their members supply the kind discriminator directly

NumericValue ::: IntegerNumberValue | RealNumberValue
  // discriminator: kind

3.1 Scalar values

Scalar Value variants carry their content directly. There is no inner literal wrapper. TextValue carries an optional lang for language-tagged text; IntegerNumberValue carries a base-10 integer lexical form (datatype is fixed at xsd:integer and not carried); RealNumberValue carries a real-valued lexical form paired with the required datatype enum (decimal | float | double); BooleanValue carries a JSON boolean.

TextValue ::: object {
  "kind": "TextValue"
  value: LexicalForm
  lang?: LanguageTag
}
  // lang, when present, MUST be a well-formed BCP 47 tag
  // value MUST be in Unicode Normalization Form C

IntegerNumberValue ::: object {
  "kind": "IntegerNumberValue"
  value: LexicalForm
}
  // value is a base-10 integer lexical form
  // datatype is implicit (xsd:integer) and not carried on the wire

RealNumberValue ::: object {
  "kind": "RealNumberValue"
  value: LexicalForm
  datatype: RealNumberDatatypeKind
}
  // value is a base-10 real-valued lexical form
  // datatype names the XSD datatype (xsd:decimal, xsd:float, or xsd:double)

BooleanValue ::: object {
  "kind": "BooleanValue"
  value: boolean
}
  // value is a JSON boolean (true or false)
  // datatype is implicit (xsd:boolean) and not carried on the wire

3.2 Temporal values

Each temporal Value variant carries its lexical form directly. The datatype is fixed by the variant’s kind and is not carried on the wire.

DateValue ::: YearValue | YearMonthValue | FullDateValue
  // discriminator: kind

YearValue ::: object {
  "kind": "YearValue"
  value: LexicalForm
}
  // value matches YYYY

YearMonthValue ::: object {
  "kind": "YearMonthValue"
  value: LexicalForm
}
  // value matches YYYY-MM

FullDateValue ::: object {
  "kind": "FullDateValue"
  value: LexicalForm
}
  // value is an xsd:date lexical form (YYYY-MM-DD with optional zone)

TimeValue ::: object {
  "kind": "TimeValue"
  value: LexicalForm
}
  // value is an xsd:time lexical form

DateTimeValue ::: object {
  "kind": "DateTimeValue"
  value: LexicalForm
}
  // value is an xsd:dateTime lexical form

3.3 Controlled-term value

Label ::: MultilingualString
Notation ::: string
PreferredLabel ::: MultilingualString

ControlledTermValue ::: object {
  "kind": "ControlledTermValue"
  term: TermIri
  label?: Label
  notation?: Notation
  preferredLabel?: PreferredLabel
}
  // term is a TermIri (an Iri identifying the term)

3.4 Enum value

EnumValue ::: object {
  "kind": "EnumValue"
  value: Token
}
  // value is the canonical Token of one of the referenced
  // EnumFieldSpec's PermissibleValue entries
  // value MUST be a non-empty Unicode string

EnumValue.value carries the wire-form of the abstract grammar’s Token slot — the wire property name is value for consistency with other Value variants, while the abstract production names the slot Token. Token is defined in §7 alongside PermissibleValue.

3.5 Link value

LinkValue ::: object {
  "kind": "LinkValue"
  iri: Iri
  label?: Label
}

3.6 Contact values

EmailValue ::: object {
  "kind": "EmailValue"
  value: LexicalForm
}

PhoneNumberValue ::: object {
  "kind": "PhoneNumberValue"
  value: LexicalForm
}

3.7 External authority values

ExternalAuthorityValue ::: OrcidValue | RorValue | DoiValue
                         | PubMedIdValue | RridValue | NihGrantIdValue
  // discriminator: kind

OrcidValue ::: object {
  "kind": "OrcidValue"
  iri: OrcidIri
  label?: Label
}

RorValue ::: object {
  "kind": "RorValue"
  iri: RorIri
  label?: Label
}

DoiValue ::: object {
  "kind": "DoiValue"
  iri: DoiIri
  label?: Label
}

PubMedIdValue ::: object {
  "kind": "PubMedIdValue"
  iri: PubMedIri
  label?: Label
}

RridValue ::: object {
  "kind": "RridValue"
  iri: RridIri
  label?: Label
}

NihGrantIdValue ::: object {
  "kind": "NihGrantIdValue"
  iri: NihGrantIri
  label?: Label
}

The typed external-authority IRI productions collapse to plain string IRIs on the wire — see §1.6.

OrcidIri ::: Iri
RorIri ::: Iri
DoiIri ::: Iri
PubMedIri ::: Iri
RridIri ::: Iri
NihGrantIri ::: Iri

3.8 Attribute value

AttributeName ::: string

AttributeValue ::: object {
  "kind": "AttributeValue"
  name: AttributeName
  value: Value
}
  // value is a tagged Value carrying its kind discriminator per §1.5.

4. Identifiers (artifact)

Each artifact identifier wire-encodes as an Iri (which itself collapses to a plain string IRI per §1.6); the abstract grammar’s typed-role distinction is not visible on the wire.

FieldId is the umbrella union of the twenty typed XxxFieldId families per grammar.md; on the wire its encoding is just the encoding of whichever family member is at the slot position, which in every case is Iri. The wire grammar therefore lists `FieldId

:: Iri` alongside each typed family for consistency.

FieldId ::: Iri
TextFieldId ::: Iri
IntegerNumberFieldId ::: Iri
RealNumberFieldId ::: Iri
BooleanFieldId ::: Iri
DateFieldId ::: Iri
TimeFieldId ::: Iri
DateTimeFieldId ::: Iri
ControlledTermFieldId ::: Iri
SingleValuedEnumFieldId ::: Iri
MultiValuedEnumFieldId ::: Iri
LinkFieldId ::: Iri
EmailFieldId ::: Iri
PhoneNumberFieldId ::: Iri
OrcidFieldId ::: Iri
RorFieldId ::: Iri
DoiFieldId ::: Iri
PubMedIdFieldId ::: Iri
RridFieldId ::: Iri
NihGrantIdFieldId ::: Iri
AttributeValueFieldId ::: Iri

TemplateId ::: Iri
PresentationComponentId ::: Iri
TemplateInstanceId ::: Iri

The family of an identifier is recovered from the kind discriminator on the enclosing object — Field and EmbeddedField for FieldId variants, Template and EmbeddedTemplate for TemplateId, PresentationComponent and EmbeddedPresentationComponent for PresentationComponentId, and TemplateInstance for TemplateInstanceId. The identifier shape itself carries no family information.

The same identifier productions serve at both the definition site of a reusable artifact (e.g. Field.id, Template.id) and the reference site where it is embedded (e.g. EmbeddedField.artifactRef, EmbeddedTemplate.artifactRef); the abstract grammar does not distinguish reference-typed productions from identity-typed ones, and on the wire both positions encode as a plain IRI string.

5. Catalog Metadata

5.1 Aggregate structure

CatalogMetadata is flat on the wire: its descriptive properties (preferredLabel, description, identifier, altLabels), its lifecycle slot, and its annotations slot are all direct members of the same object — there is no descriptiveMetadata wrapper.

Description ::: MultilingualString
Identifier ::: string
AlternativeLabel ::: MultilingualString

CatalogMetadata ::: object {
  preferredLabel?: PreferredLabel
  description?: Description
  identifier?: Identifier
  altLabels?: array<AlternativeLabel>
  lifecycle: LifecycleMetadata
  annotations?: array<Annotation>
}
  // preferredLabel is the artifact's catalog-display name. It is
  // distinct from a schema artifact's *rendered* display name, which
  // lives on a top-level slot on the artifact itself (Field.label,
  // Template.title, TemplateInstance.label).
  // altLabels SHOULD be omitted from the wire when empty; it round-trips
  // as an empty array in memory
  // annotations SHOULD be omitted from the wire when empty; it round-trips
  // as an empty array in memory
  // the grammar's Description, PreferredLabel, and AlternativeLabel
  // productions are MultilingualString-typed wrappers that collapse on
  // the wire (§1.6); the type names appear here for parity with the
  // abstract grammar's component naming

CatalogMetadata is uniform across every artifact kind: Field, Template, PresentationComponent, and TemplateInstance all carry the same CatalogMetadata shape under the wire-form metadata key.

Schema artifacts (Field, Template) additionally carry SchemaArtifactVersioning as a separate top-level versioning slot on the artifact itself; non-schema artifacts (PresentationComponent, TemplateInstance) do not carry versioning. The SchemaArtifactMetadata wrapper production used in prior revisions of this specification is removed: in the new shape, schema artifacts carry metadata and versioning as parallel top-level slots rather than as a single metadata-wrapped blob.

5.2 Lifecycle metadata

CreatedOn ::: string
CreatedBy ::: string
ModifiedOn ::: string
ModifiedBy ::: string

LifecycleMetadata ::: object {
  createdOn: CreatedOn
  createdBy: CreatedBy
  modifiedOn: ModifiedOn
  modifiedBy: ModifiedBy
}
  // createdOn and modifiedOn carry IsoDateTimeStamp values
  // createdBy and modifiedBy carry agent Iri values

5.3 Schema versioning

SchemaArtifactVersioning ::: object {
  version: Version
  status: Status
  previousVersion?: PreviousVersion
  derivedFrom?: DerivedFrom
}
  // version is a SemanticVersion lexical form
  // when both previousVersion and derivedFrom are present, they MUST
  // NOT carry the same IRI (per grammar.md §Schema Artifact
  // Versioning); succession and derivation are mutually exclusive at
  // any single point

Version ::: string
ModelVersion ::: string
  // a SemanticVersion 2.0.0 lexical form; carried directly on every
  // concrete artifact wire object as the top-level `modelVersion` slot
PreviousVersion ::: Iri
DerivedFrom ::: Iri

Status ::: "draft" | "published"

5.4 Annotations

Annotation ::: object {
  property: Iri
  body: AnnotationValue
}
  // property is the annotation-property Iri (the grammar's bare Iri
  // collapses to a string per §1.6)

AnnotationValue ::: AnnotationStringValue | AnnotationIriValue
  // discriminator: kind

AnnotationStringValue ::: object {
  "kind": "AnnotationStringValue"
  value: LexicalForm
  lang?: LanguageTag
}
  // lang, when present, MUST be a well-formed BCP 47 tag
  // value MUST be in Unicode Normalization Form C

AnnotationIriValue ::: object {
  "kind": "AnnotationIriValue"
  iri: Iri
}
  // iri carries an Iri value (RFC 3987)

6. Embedded Artifact Properties

6.1 Embedded artifact key

EmbeddedArtifactKey ::: string
  // matches the pattern [A-Za-z][A-Za-z0-9_-]*
  // unique within the containing Template (constraint enforced on Template)

6.2 Requirements

ValueRequirement ::: "required" | "recommended" | "optional"

6.3 Cardinality

Cardinality ::: object {
  min: MinCardinality
  max?: MaxCardinality
}
  // min is a non-negative integer
  // max omitted ⇒ unbounded above (per grammar.md §Cardinality)

MinCardinality ::: number
MaxCardinality ::: number

6.4 Visibility

Visibility ::: "visible" | "hidden"

6.5 Defaults

Defaults are specified at two layers, with parallel typing per family. See grammar.md §Defaults for the abstract grammar’s full treatment, including precedence and the UI/UX-only semantics; this section gives the wire form.

Embedding-level defaults. The optional defaultValue slot on each EmbeddedXxxField is typed family-by-family with the family’s Value type. There is no DefaultValue union and no per-family XxxDefaultValue wrapper on the wire: the defaultValue JSON encodes directly as the corresponding family’s Value. Per the kind rule (§1.5), every Value family is a member of the Value discriminator-kind union, so every embedding-level defaultValue carries a kind discriminator on the wire.

EmbeddedAttributeValueField has no defaultValue slot (per §9).

Field-level defaults. Every XxxFieldSpec (with one exception) carries an optional defaultValue slot whose type matches its embedding-level counterpart. The two layers are independent: a field MAY ship with a field-level default and a Template embedding that field MAY override that default with an embedding-level defaultValue (see grammar.md §Defaults for the full precedence rule). The wire shapes are identical to the embedding-level table above, with the following per-family details:

• TextFieldSpec.defaultValue?: TextValue

• IntegerNumberFieldSpec.defaultValue?: IntegerNumberValue

• RealNumberFieldSpec.defaultValue?: RealNumberValue

• BooleanFieldSpec.defaultValue?: BooleanValue

• DateFieldSpec.defaultValue?: DateValue (the arm MUST be consistent with dateValueType)

• TimeFieldSpec.defaultValue?: TimeValue

• DateTimeFieldSpec.defaultValue?: DateTimeValue

• ControlledTermFieldSpec.defaultValue?: ControlledTermValue

• LinkFieldSpec.defaultValue?: LinkValue

• EmailFieldSpec.defaultValue?: EmailValue

• PhoneNumberFieldSpec.defaultValue?: PhoneNumberValue

• OrcidFieldSpec.defaultValue?: OrcidValue

• RorFieldSpec.defaultValue?: RorValue

• DoiFieldSpec.defaultValue?: DoiValue

• PubMedIdFieldSpec.defaultValue?: PubMedIdValue

• RridFieldSpec.defaultValue?: RridValue

• NihGrantIdFieldSpec.defaultValue?: NihGrantIdValue

• SingleValuedEnumFieldSpec.defaultValue?: EnumValue — a tagged EnumValue whose value MUST equal the Token of one of the spec’s permissible-value entries.

• MultiValuedEnumFieldSpec.defaultValues?: array<EnumValue> — a (possibly empty) JSON array of tagged EnumValue entries; each value MUST equal the Token of one of the spec’s permissible-value entries, and the array MUST NOT contain duplicate value entries.

AttributeValueFieldSpec carries no field-level default.

6.6 Label override

LabelOverride ::: object {
  label: Label
  altLabels: array<AlternativeLabel>
}
  // altLabels MAY be empty

6.7 Help text

HelpText ::: MultilingualString
HelpTextOverride ::: MultilingualString

Both productions collapse on the wire per the wrapper-collapse rule (§1.6): a MultilingualString is encoded as a non-empty array of LangString entries. HelpText is carried by the reusable Field artifact (slot helpText?); HelpTextOverride is carried by each EmbeddedXxxField (slot helpTextOverride?).

6.8 Properties

Property ::: object {
  iri: PropertyIri
  label?: PropertyLabel
}
  // iri carries the PropertyIri; label is the optional PropertyLabel

PropertyIri ::: Iri
PropertyLabel ::: MultilingualString

7. Field Specs

FieldSpec ::: TextFieldSpec | NumericFieldSpec | BooleanFieldSpec
            | TemporalFieldSpec
            | ControlledTermFieldSpec | EnumFieldSpec | LinkFieldSpec
            | ContactFieldSpec | ExternalAuthorityFieldSpec
            | AttributeValueFieldSpec
  // discriminator: kind
  // NumericFieldSpec, TemporalFieldSpec, EnumFieldSpec, ContactFieldSpec,
  // and ExternalAuthorityFieldSpec are unions; their members supply
  // the kind discriminator directly

NumericFieldSpec ::: IntegerNumberFieldSpec | RealNumberFieldSpec
  // discriminator: kind

TextFieldSpec ::: object {
  "kind": "TextFieldSpec"
  defaultValue?: TextValue
  minLength?: MinLength
  maxLength?: MaxLength
  validationRegex?: ValidationRegex
  langTagRequirement?: LangTagRequirement
  renderingHint?: TextRenderingHint
}

LangTagRequirement ::: "langTagRequired" | "langTagOptional" | "langTagForbidden"
  // defaultValue, when present, encodes as a tagged TextValue per
  // the kind rule (§1.5): `{ "kind": "TextValue", "value": ..., "lang"?: ... }`.
  // See §6.5 for default-value semantics across all field families.

IntegerNumberFieldSpec ::: object {
  "kind": "IntegerNumberFieldSpec"
  defaultValue?: IntegerNumberValue
  unit?: Unit
  minValue?: IntegerNumberMinValue
  maxValue?: IntegerNumberMaxValue
  renderingHint?: NumericRenderingHint
}

RealNumberFieldSpec ::: object {
  "kind": "RealNumberFieldSpec"
  datatype: RealNumberDatatypeKind
  defaultValue?: RealNumberValue
  unit?: Unit
  minValue?: RealNumberMinValue
  maxValue?: RealNumberMaxValue
  renderingHint?: NumericRenderingHint
}

BooleanFieldSpec ::: object {
  "kind": "BooleanFieldSpec"
  defaultValue?: BooleanValue
  renderingHint?: BooleanRenderingHint
}

Unit ::: object {
  iri: Iri
  label?: Label
}

MinLength ::: number
MaxLength ::: number
ValidationRegex ::: string
DecimalPlaces ::: number
IntegerNumberMinValue ::: IntegerNumberValue
IntegerNumberMaxValue ::: IntegerNumberValue
RealNumberMinValue ::: RealNumberValue
RealNumberMaxValue ::: RealNumberValue

7.1 Temporal field specs

TemporalFieldSpec ::: DateFieldSpec | TimeFieldSpec | DateTimeFieldSpec
  // discriminator: kind

DateFieldSpec ::: object {
  "kind": "DateFieldSpec"
  dateValueType: DateValueType
  defaultValue?: DateValue
  renderingHint?: DateRenderingHint
}
  // defaultValue, when present, MUST be a DateValue arm consistent
  // with dateValueType (e.g. dateValueType "year" admits only YearValue).

DateValueType ::: "year" | "yearMonth" | "fullDate"

TimeFieldSpec ::: object {
  "kind": "TimeFieldSpec"
  defaultValue?: TimeValue
  timePrecision?: TimePrecision
  timezoneRequirement?: TimezoneRequirement
  renderingHint?: TimeRenderingHint
}

TimePrecision ::: "hourMinute" | "hourMinuteSecond" | "hourMinuteSecondFraction"

TimezoneRequirement ::: "timezoneRequired" | "timezoneNotRequired"

DateTimeFieldSpec ::: object {
  "kind": "DateTimeFieldSpec"
  dateTimeValueType: DateTimeValueType
  defaultValue?: DateTimeValue
  timezoneRequirement?: TimezoneRequirement
  renderingHint?: DateTimeRenderingHint
}

DateTimeValueType ::: "dateHourMinute" | "dateHourMinuteSecond"
                    | "dateHourMinuteSecondFraction"

DateRenderingHint ::: object {
  componentOrder?: DateComponentOrder
  placeholder?: Placeholder
}

DateComponentOrder ::: "dayMonthYear" | "monthDayYear" | "yearMonthDay"

TimeRenderingHint ::: object {
  timeFormat?: TimeFormat
  placeholder?: Placeholder
}

DateTimeRenderingHint ::: object {
  timeFormat?: TimeFormat
  placeholder?: Placeholder
}

TimeFormat ::: "twelveHour" | "twentyFourHour"

7.2 Controlled term field spec

ControlledTermFieldSpec ::: object {
  "kind": "ControlledTermFieldSpec"
  defaultValue?: ControlledTermValue
  sources: nonEmptyArray<ControlledTermSource>
  renderingHint?: ControlledTermRenderingHint
}
  // defaultValue.term, when present, SHOULD belong to one of the
  // declared sources, but the structural model does not enforce this

7.3 Enum field specs

EnumFieldSpec ::: SingleValuedEnumFieldSpec | MultiValuedEnumFieldSpec
  // discriminator: kind

SingleValuedEnumFieldSpec ::: object {
  "kind": "SingleValuedEnumFieldSpec"
  permissibleValues: nonEmptyArray<PermissibleValue>
  defaultValue?: EnumValue
  renderingHint?: SingleValuedEnumRenderingHint
}
  // defaultValue.value, when present, MUST equal the `value` of one
  // of the permissibleValues entries

MultiValuedEnumFieldSpec ::: object {
  "kind": "MultiValuedEnumFieldSpec"
  permissibleValues: nonEmptyArray<PermissibleValue>
  defaultValues?: array<EnumValue>
  renderingHint?: MultiValuedEnumRenderingHint
}
  // defaultValues, when present, is a (possibly empty) array of
  // EnumValue entries; each defaultValues[i].value MUST equal the
  // `value` of one of the permissibleValues entries; the array MUST
  // NOT contain duplicate `value` entries

PermissibleValue ::: object {
  value: Token
  label?: Label
  description?: Description
  meanings?: array<Meaning>
}
  // value carries the canonical Token of the permissible value and
  // MUST be a non-empty Unicode string
  // value MUST be unique within the enclosing spec's permissibleValues
  // meanings, when present, is a (possibly empty) array of Meaning
  // objects binding the token to ontology terms; SHOULD be omitted
  // when empty

Token ::: string
  // a non-empty Unicode string serving as the canonical key of a
  // PermissibleValue or the value carried by an EnumValue

Meaning ::: object {
  iri: TermIri
  label?: Label
}
  // iri carries the TermIri of the bound ontology term
  // label, when present, is the cached human-readable label of the
  // bound term (distinct from the enclosing PermissibleValue's label,
  // which is the label of the permissible value itself)

7.4 Other field specs

LinkFieldSpec ::: object {
  "kind": "LinkFieldSpec"
  defaultValue?: LinkValue
  renderingHint?: LinkRenderingHint
}

ContactFieldSpec ::: EmailFieldSpec | PhoneNumberFieldSpec
  // discriminator: kind

EmailFieldSpec ::: object {
  "kind": "EmailFieldSpec"
  defaultValue?: EmailValue
  renderingHint?: EmailRenderingHint
}

PhoneNumberFieldSpec ::: object {
  "kind": "PhoneNumberFieldSpec"
  defaultValue?: PhoneNumberValue
  renderingHint?: PhoneNumberRenderingHint
}

ExternalAuthorityFieldSpec ::: OrcidFieldSpec | RorFieldSpec | DoiFieldSpec
                             | PubMedIdFieldSpec | RridFieldSpec
                             | NihGrantIdFieldSpec
  // discriminator: kind

OrcidFieldSpec ::: object {
  "kind": "OrcidFieldSpec"
  defaultValue?: OrcidValue
  renderingHint?: OrcidRenderingHint
}

RorFieldSpec ::: object {
  "kind": "RorFieldSpec"
  defaultValue?: RorValue
  renderingHint?: RorRenderingHint
}

DoiFieldSpec ::: object {
  "kind": "DoiFieldSpec"
  defaultValue?: DoiValue
  renderingHint?: DoiRenderingHint
}

PubMedIdFieldSpec ::: object {
  "kind": "PubMedIdFieldSpec"
  defaultValue?: PubMedIdValue
  renderingHint?: PubMedIdRenderingHint
}

RridFieldSpec ::: object {
  "kind": "RridFieldSpec"
  defaultValue?: RridValue
  renderingHint?: RridRenderingHint
}

NihGrantIdFieldSpec ::: object {
  "kind": "NihGrantIdFieldSpec"
  defaultValue?: NihGrantIdValue
  renderingHint?: NihGrantIdRenderingHint
}

AttributeValueFieldSpec ::: object {
  "kind": "AttributeValueFieldSpec"
}
  // AttributeValueFieldSpec carries no defaultValue; an AttributeValue
  // is a per-instance pairing of a name and a value, and a default is
  // not meaningful here (see grammar.md §Defaults).

7.5 Controlled term sources

ControlledTermSource ::: OntologySource | BranchSource
                       | ClassSource | ValueSetSource
  // discriminator: kind

OntologySource ::: object {
  "kind": "OntologySource"
  ontology: OntologyReference
}

OntologyReference ::: object {
  iri: OntologyIri
  displayHint?: OntologyDisplayHint
}

OntologyDisplayHint ::: object {
  acronym?: OntologyAcronym
  name?: OntologyName
}
  // at least one of acronym, name MUST be present

BranchSource ::: object {
  "kind": "BranchSource"
  ontology: OntologyReference
  rootTermIri: RootTermIri
  rootTermLabel?: RootTermLabel
  maxTraversalDepth?: MaxTraversalDepth
}
  // rootTermLabel SHOULD be present (captured at source-declaration time)
  // but MAY be omitted when the term's display text is not available

ClassSource ::: object {
  "kind": "ClassSource"
  classes: nonEmptyArray<ControlledTermClass>
}

ControlledTermClass ::: object {
  term: TermIri
  label?: Label
  ontology: OntologyReference
}
  // term is a TermIri
  // label SHOULD be present (captured at source-declaration time)
  // but MAY be omitted when the term's display text is not available

ValueSetSource ::: object {
  "kind": "ValueSetSource"
  identifier: ValueSetIdentifier
  name?: ValueSetName
  iri?: ValueSetIri
}

OntologyAcronym ::: string
OntologyName ::: MultilingualString
OntologyIri ::: Iri
RootTermIri ::: Iri
RootTermLabel ::: MultilingualString
MaxTraversalDepth ::: number
ValueSetIdentifier ::: string
ValueSetName ::: MultilingualString
ValueSetIri ::: Iri

The leaf productions used by the controlled-term sources collapse on the wire per §1.6; their ::: definitions are listed alongside the source productions for slot-type reference.

7.6 Rendering hints

The RenderingHint union is heterogeneous: text/enum/boolean hints encode as flat strings, while DateRenderingHint, TimeRenderingHint, DateTimeRenderingHint, and NumericRenderingHint encode as objects that can carry configuration. Because some members are strings (which cannot carry a "kind" property), the union uses discriminator: position (§1.3): the decoder identifies the variant from the enclosing FieldSpec’s family — e.g. the value at TextFieldSpec.renderingHint is decoded as a TextRenderingHint, the value at SingleValuedEnumFieldSpec.renderingHint as a SingleValuedEnumRenderingHint, and so on.

RenderingHint ::: TextRenderingHint | SingleValuedEnumRenderingHint
                | MultiValuedEnumRenderingHint | NumericRenderingHint
                | BooleanRenderingHint
                | DateRenderingHint | TimeRenderingHint | DateTimeRenderingHint
                | ControlledTermRenderingHint
                | EmailRenderingHint | PhoneNumberRenderingHint
                | LinkRenderingHint
                | OrcidRenderingHint | RorRenderingHint | DoiRenderingHint
                | PubMedIdRenderingHint | RridRenderingHint
                | NihGrantIdRenderingHint
  // discriminator: position
  // resolved by the renderingHint property of the enclosing FieldSpec

TextRenderingHint ::: object {
  lineMode?: TextLineMode
  placeholder?: Placeholder
}

TextLineMode ::: "singleLine" | "multiLine"

SingleValuedEnumRenderingHint ::: "radio" | "dropdown"

MultiValuedEnumRenderingHint ::: "checkbox" | "multiSelect"

NumericRenderingHint ::: object {
  decimalPlaces?: DecimalPlaces
  placeholder?: Placeholder
}
  // decimalPlaces, when present, MUST be a non-negative integer
  // it is a presentation concern (display rounding); it does NOT
  // constrain the lexical form of submitted values

BooleanRenderingHint ::: "checkbox" | "toggle" | "radio" | "dropdown"

ControlledTermRenderingHint ::: object { placeholder?: Placeholder }
EmailRenderingHint          ::: object { placeholder?: Placeholder }
PhoneNumberRenderingHint    ::: object { placeholder?: Placeholder }
LinkRenderingHint           ::: object { placeholder?: Placeholder }
OrcidRenderingHint          ::: object { placeholder?: Placeholder }
RorRenderingHint            ::: object { placeholder?: Placeholder }
DoiRenderingHint            ::: object { placeholder?: Placeholder }
PubMedIdRenderingHint       ::: object { placeholder?: Placeholder }
RridRenderingHint           ::: object { placeholder?: Placeholder }
NihGrantIdRenderingHint     ::: object { placeholder?: Placeholder }

Placeholder ::: MultilingualString

Placeholder collapses on the wire per the wrapper-collapse rule (§1.6).

8. Field artifacts

Field ::: TextField | NumericField | BooleanField
        | DateField | TimeField | DateTimeField
        | ControlledTermField
        | SingleValuedEnumField | MultiValuedEnumField
        | LinkField | EmailField | PhoneNumberField
        | OrcidField | RorField | DoiField | PubMedIdField
        | RridField | NihGrantIdField | AttributeValueField
  // discriminator: kind
  // NumericField is itself a union of IntegerNumberField and RealNumberField

NumericField ::: IntegerNumberField | RealNumberField
  // discriminator: kind

TemporalField ::: DateField | TimeField | DateTimeField
  // discriminator: kind
  // a documented intermediate category; the wire form is just the variant

EnumField ::: SingleValuedEnumField | MultiValuedEnumField
  // discriminator: kind

ContactField ::: EmailField | PhoneNumberField
  // discriminator: kind

ExternalAuthorityField ::: OrcidField | RorField | DoiField
                         | PubMedIdField | RridField | NihGrantIdField
  // discriminator: kind

TextField ↗ EmbeddedTextField ::: object {
  "kind": "TextField"
  id: TextFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: TextFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

IntegerNumberField ↗ EmbeddedIntegerNumberField ::: object {
  "kind": "IntegerNumberField"
  id: IntegerNumberFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: IntegerNumberFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

RealNumberField ↗ EmbeddedRealNumberField ::: object {
  "kind": "RealNumberField"
  id: RealNumberFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: RealNumberFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

BooleanField ↗ EmbeddedBooleanField ::: object {
  "kind": "BooleanField"
  id: BooleanFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: BooleanFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

DateField ↗ EmbeddedDateField ::: object {
  "kind": "DateField"
  id: DateFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: DateFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

TimeField ↗ EmbeddedTimeField ::: object {
  "kind": "TimeField"
  id: TimeFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: TimeFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

DateTimeField ↗ EmbeddedDateTimeField ::: object {
  "kind": "DateTimeField"
  id: DateTimeFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: DateTimeFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

ControlledTermField ↗ EmbeddedControlledTermField ::: object {
  "kind": "ControlledTermField"
  id: ControlledTermFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: ControlledTermFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

SingleValuedEnumField ↗ EmbeddedSingleValuedEnumField ::: object {
  "kind": "SingleValuedEnumField"
  id: SingleValuedEnumFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: SingleValuedEnumFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

MultiValuedEnumField ↗ EmbeddedMultiValuedEnumField ::: object {
  "kind": "MultiValuedEnumField"
  id: MultiValuedEnumFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: MultiValuedEnumFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

LinkField ↗ EmbeddedLinkField ::: object {
  "kind": "LinkField"
  id: LinkFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: LinkFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

EmailField ↗ EmbeddedEmailField ::: object {
  "kind": "EmailField"
  id: EmailFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: EmailFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

PhoneNumberField ↗ EmbeddedPhoneNumberField ::: object {
  "kind": "PhoneNumberField"
  id: PhoneNumberFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: PhoneNumberFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

OrcidField ↗ EmbeddedOrcidField ::: object {
  "kind": "OrcidField"
  id: OrcidFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: OrcidFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

RorField ↗ EmbeddedRorField ::: object {
  "kind": "RorField"
  id: RorFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: RorFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

DoiField ↗ EmbeddedDoiField ::: object {
  "kind": "DoiField"
  id: DoiFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: DoiFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

PubMedIdField ↗ EmbeddedPubMedIdField ::: object {
  "kind": "PubMedIdField"
  id: PubMedIdFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: PubMedIdFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

RridField ↗ EmbeddedRridField ::: object {
  "kind": "RridField"
  id: RridFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: RridFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

NihGrantIdField ↗ EmbeddedNihGrantIdField ::: object {
  "kind": "NihGrantIdField"
  id: NihGrantIdFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: NihGrantIdFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form

AttributeValueField ↗ EmbeddedAttributeValueField ::: object {
  "kind": "AttributeValueField"
  id: AttributeValueFieldId
  modelVersion: ModelVersion
  metadata: CatalogMetadata
  versioning: SchemaArtifactVersioning
  fieldSpec: AttributeValueFieldSpec
  label: Label
  helpText?: HelpText
}
  // modelVersion is a SemanticVersion 2.0.0 lexical form