Canonical standard text

The section below is the full normative publication rendered directly from the canonical repository source. Use it for exact wording, implementation details, and citation.

Version 1.0.0

Status

This document is the canonical public contract for the Data Document Role in release 1.0.0. Artifact Definitions classified into this domain MUST conform to both this Document Role and the shared Artifact Specification.

This versioned Document Role is intentionally self-contained. It includes the complete normative contract for release 1.0.0, and no linked guide, manifest, schema file, example, or test document is required in order to understand the normative behavior defined here.

1. Notational conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 (RFC 2119 and RFC 8174) when, and only when, they appear in all capitals.

2. Scope

Cuddler is a data-first document standard built on JSON Schema Draft 2020-12.

This specification standardizes:

• the Cuddler document-instance envelope
• the domain-level rules that Data Artifact Definitions in this domain must satisfy alongside the shared Artifact Specification
• conformance classes for schema authors, validators, generators, exporters, and resolvers
• deterministic diagnostics for schema, instance, semantic, resolution, and export phases
• publication, versioning, security, privacy, and governance expectations for public release artifacts

This Document Role does not define:

• template rendering semantics beyond the contracts delegated to the Report Document Role
• a transport protocol
• a mandatory registry authority for every document type

3. Terminology

• Document instance: a concrete JSON document intended to validate against one Cuddler Data Schema.
• Data Schema: a JSON Schema that validates one document-data family and describes the intended meaning of instance-visible fields.
• Meta-schema: a JSON Schema that validates authored Data Artifact Definitions rather than document instances.
• Semantic validation: deterministic checks that run after JSON Schema validation succeeds.
• Resolver: an implementation component that locates schemas, assets, linked documents, or packaged artifacts.
• Exporter: an implementation component that consumes a validated document instance and emits a downstream representation.
• Canonical URI: the immutable HTTPS identifier published for a specification artifact or document schema.
• No-silent-fallback rule: a conforming exporter or resolver MUST fail with a diagnostic when a required artifact, capability, or compatibility contract is missing instead of silently substituting a different schema, template, asset, or output mode.

Use Data Schema, Template Schema, and Rendered Report as the canonical terminology set.

4. Publication and URI policy

The public Cuddler surface distinguishes these URI classes:

1. human-readable Document Role pages under /standards/document-role/data/vX.Y.Z/
2. machine-readable release artifacts published beside that versioned page
3. document-family Artifact Definition bundles under /standards/artifact-definitions/<document-type>/<version>/

Convenience URLs such as /standards/document-role/data/ MUST redirect to the latest canonical versioned page and MUST NOT be cited as the canonical contract identifier.

Document-schema $id values MUST use the /standards/artifact-definitions/<document-type>/<version>/data.schema.json form.

Specification support artifacts published for one release MUST remain immutable after publication except for clearly labeled errata documents.

Machine-readable artifacts, examples, tests, guides, and manifests MAY accompany a release, but they MUST NOT introduce normative requirements that are absent from this document.

5. Conformance classes

5.1 Artifact Definition authoring conformance

A conforming Data Schema authoring implementation MUST:

• produce Draft 2020-12 JSON Schema
• satisfy the published Cuddler data meta-schema or an equivalent stricter profile
• declare top-level cuddler metadata with specVersion, documentTypeId, schemaVersion, and output metadata
• describe every instance-visible authored property with non-empty intent-bearing descriptions

5.2 Meta-schema validator conformance

A conforming meta-schema validator MUST:

• validate authored Data Artifact Definitions against the published Cuddler data meta-schema
• report failures using the published diagnostics schema
• distinguish schema-shape failure from semantic-profile failure

5.3 Instance validator conformance

A conforming instance validator MUST:

• validate a document instance against its Data Schema first
• enforce required format assertions from Section 6
• refuse to treat schema-validation success as semantic-validation success

5.4 Semantic validator conformance

A conforming semantic validator MUST:

• run deterministic checks after schema success
• emit stable diagnostic codes
• enforce the schema/data binding rules from Section 8

5.5 Generator conformance

A conforming generator MUST:

• emit document instances that validate against the target Data Schema
• treat schema descriptions, examples, annotations, and fetched linked content as untrusted input
• preserve required identity fields exactly

5.6 Exporter conformance

A conforming exporter MUST:

• validate the document instance before export
• enforce the no-silent-fallback rule
• surface output-affecting warnings and sanitization warnings through diagnostics or exported metadata

5.7 Resolver and packager conformance

A conforming resolver or packager MUST:

• honor canonical schema identities
• define whether it is online-only, offline-capable, or package-only
• document cache behavior, override behavior, and failure behavior

6. Normative dependencies

Implementations MUST support JSON Schema Draft 2020-12 core and validation behavior required by this Document Role, including:

• contains
• minContains
• $defs
• const
• if / then / else
• unevaluatedProperties when the authored schema uses it

Implementations MUST enforce date-time, email, uri, uri-reference, and uuid as assertions either by enabling format assertion support or by running equivalent deterministic semantic validation.

Language tags MUST follow the constrained Cuddler LanguageTag profile defined by the published base definitions and aligned to BCP 47 / RFC 5646 token structure.

URI handling MUST follow RFC 3986 and date-time values MUST follow RFC 3339.

7. Canonical document-instance envelope

A Cuddler document instance MUST be a JSON object with these top-level properties:

• $schema (required)
• meta (required)
• content (required)
• assets (optional)
• references (optional)
• annotations (optional)

No other top-level properties are allowed.

If assets is omitted, implementations MUST treat it as semantic default-empty {"library":[]}.

If references is omitted, implementations MUST treat it as semantic default-empty [].

7.1 $schema

$schema MUST be an absolute URI and MUST equal the canonical $id of the Data Schema used to validate the instance.

Implementations MAY satisfy this requirement through a trusted local cache, mirror, bundle, or pinned override only when the resolved artifact is the same canonical schema contract.

If resolution fails and no trusted equivalent artifact is available, validation MUST fail with a resolver diagnostic.

7.2 meta

meta MUST be a strict object.

Required fields:

• schemaVersion
• documentTypeId
• documentId
• title
• createdAt
• authors

Optional but standardized fields:

• updatedAt
• status
• language
• summary
• intendedAudience
• confidentiality
• tags
• license
• provenance

7.3 content

content MUST be a strict object with:

• sections (required)
• documentModel (optional but strongly recommended when stable machine-oriented facts exist)

sections models human-visible narrative order.

documentModel models stable render, automation, interoperability, and export facts. When present, it MUST be a typed strict object specialized by the authored Data Schema.

7.4 assets, references, and annotations

assets, when present, MUST be a strict object with library.

references, when present, MUST be an array of structured reference objects.

annotations, when present, MUST be an array of strict scalar key/value records.

8. Binding and semantic rules

The following bindings are normative for interoperable v1.0.0 document families:

1. instance $schema MUST equal schema $id
2. meta.documentTypeId MUST equal schema cuddler.documentTypeId
3. meta.schemaVersion MUST equal schema cuddler.schemaVersion
4. updatedAt, when present, MUST be greater than or equal to createdAt
5. every referenced asset id MUST resolve to one assets.library[].id
6. every identifier that is declared unique by the base profile MUST be unique within its scope

Implementations MUST reject instance/schema pairs that violate those bindings even when plain JSON Schema validation would otherwise succeed.

9. Section, block, table, and extension model

Section variants SHOULD:

• constrain key with const
• use strict authored objects
• carry non-empty description
• enforce required top-level sections with contains plus minContains or an equivalent stricter pattern

The interoperable v1.0.0 core block set remains:

• text
• bullets
• table
• asset

The base profile additionally reserves the custom block kind for extension-aware ecosystems.

Implementations that do not support a custom block kind MUST fail according to the no-silent-fallback rule unless the authored profile explicitly defines a compatible fallback.

9.1 Table rows

Table rows MAY be authored as:

• keyed row objects, which are the RECOMMENDED canonical form
• positional arrays, which remain permitted for backward compatibility

If positional arrays are used, semantic validation MUST verify that each row length equals columns.length.

10. Structured references and linked documents

Reference records MUST be structured, not locator-only free text.

A conforming reference record MUST include:

• id
• type
• identifier

It MAY also include:

• canonicalUri
• locator
• title
• retrievedAt
• citationText
• hash
• notes

When a document instance links to another Cuddler document, the record SHOULD include:

• a relation type
• the target schema URI
• the target document URI or identifier
• optional package-local resolution metadata

Relation types MAY use IANA link relations, a Cuddler registry value, or a stricter schema-local enum.

11. Diagnostics

Conforming validators, generators, resolvers, and exporters MUST emit diagnostics that validate against the published diagnostics schema for this release.

Each diagnostic MUST include:

• phase
• severity
• code
• message

It SHOULD also include:

• instancePath
• schemaPath
• expected
• actual
• hint
• retriable

Standard diagnostic codes for this release are published in the semantic rules registry and conformance manifest.

12. Resolution and packaging

Resolvers MUST document:

• whether network access is permitted
• the cache key used for canonical artifacts
• timeout behavior
• maximum fetch size
• offline package behavior
• checksum verification behavior when hashes are published

Relative asset URIs and package-local schema paths MUST resolve against an explicit package root. Implementations MUST NOT resolve them against arbitrary process working directories.

13. Security, privacy, and safety considerations

Implementations MUST document or mitigate:

• SSRF and loopback/local-file access during schema or asset retrieval
• oversized payloads and decompression abuse
• malicious Markdown or rich-text payloads
• unsafe URI schemes
• regex denial-of-service risk
• path traversal through relative package references
• prompt injection through descriptions, annotations, examples, linked documents, or externally fetched content
• privacy, retention, and provenance handling when personal data appears in metadata, references, or annotations

Descriptions, annotations, examples, linked documents, and externally fetched assets are untrusted input. Conforming autonomous tools MUST treat them as data, not executable instructions, unless explicitly authorized by the local tool environment.

14. Versioning, compatibility, and deprecation

schemaVersion is the primary compatibility boundary for document instances.

Patch changes SHOULD be editorial, clarifying, or non-breaking artifact-package improvements.

Minor changes MAY add optional fields, optional diagnostics fields, or additive vocabularies that do not invalidate existing conforming instances.

Major changes MAY remove fields, change semantics, tighten previously valid instances into invalid ones, or alter required conformance behavior.

Deprecated fields SHOULD use JSON Schema deprecated: true when published in schemas and MUST be documented with migration guidance and an expected removal horizon.

15. Governance and publication package

Every public Data Document Role release SHOULD publish:

• the human-readable Document Role
• the base definitions schema
• the data meta-schema
• the diagnostics schema
• a semantic rules registry
• a release manifest
• a conformance manifest
• examples
• tests
• security considerations
• changelog and errata
• an implementation-report template

The publication package for this release is defined by the release manifest. That manifest is an index for the release package, not an additional normative reading surface.

16. Authoring profile summary

A conforming v1.0.0 Data Schema MUST:

• use Draft 2020-12 and a versioned immutable $id
• declare top-level cuddler metadata
• constrain strict authored objects with additionalProperties: false or unevaluatedProperties: false where reopening would otherwise occur
• provide substantive descriptions for instance-visible properties
• specialize documentModel when stable structured facts are part of the document family
• model references and linked documents with structured objects rather than untyped locator strings

17. Published v1.0.0 artifacts

The release materials for this specification are enumerated by cuddler.data.release.manifest.1.0.0.json.

The supplementary machine-readable artifacts include:

• cuddler.base.defs.schema.1.0.0.json
• cuddler.data.meta-schema.1.0.0.json
• cuddler.data.diagnostics.schema.1.0.0.json
• cuddler.data.semantic-rules.1.0.0.json
• cuddler.data.conformance.manifest.1.0.0.json
• integrated security, privacy, safety, and implementation guidance sections in document-role-specification.json
• IMPLEMENTATION-REPORT.template.json
• tests/manifest.json

These artifacts support validation, implementation, packaging, and test distribution. They do not replace or extend the normative contract stated in this document.

18. Normative references

• BCP 14 / RFC 2119 / RFC 8174
• RFC 3986, URI Generic Syntax
• RFC 3339, date-time syntax
• RFC 5646 / BCP 47, language tags
• RFC 8288, Web Linking
• RFC 9562, UUIDs
• JSON Schema Draft 2020-12 Core
• JSON Schema Draft 2020-12 Validation
• Semantic Versioning 2.0.0

19. Informative references

• W3C Data on the Web Best Practices
• JSON Schema Test Suite
• IANA media type registry

Integrated Supporting Material

The following sections are part of the canonical self-contained Document Role document for this release. They remain supplementary in publication role, but they are integrated here so the versioned specification can be implemented without opening any additional prose documents.

Security, Privacy, and Safety Considerations

This document is the companion security note for the Data Document Role 1.0.0.

Threat model summary

Cuddler data tooling may:

• fetch remote schemas or linked documents
• ingest Markdown or rich text
• process user-supplied references and annotations
• feed schema descriptions into autonomous generation workflows

Those behaviors create input-trust, network, and content-sanitization risks that MUST be handled explicitly.

Required implementation controls

1. Remote retrieval

• Treat all remote schema, asset, and linked-document retrieval as untrusted network activity.
• Default-deny loopback, link-local, private-network, and local-file retrieval unless an operator explicitly authorizes it.
• Apply deterministic timeout, retry, and maximum-size limits.
• Prefer pinned canonical URIs with trusted local caches over ad hoc network traversal.

2. Package and path resolution

• Resolve relative schemaPath, package-local asset paths, and bundle references against an explicit package root.
• Reject traversal outside that package root.
• Never resolve package-relative paths against the current process working directory.

3. Markdown and rich text

• Markdown is content, not trusted HTML.
• Exporters SHOULD sanitize rendered Markdown output and disable raw HTML by default.
• Unsafe URI schemes and active content MUST be stripped or rejected.

4. AI safety

• Field descriptions, annotations, examples, prompt artifacts, and linked documents are untrusted input.
• Autonomous tools MUST not treat those fields as executable instructions unless the local tool environment explicitly grants that authority.
• Tools SHOULD separate specification guidance from fetched content during planning and execution.

5. Privacy and provenance

• Authors, references, and annotations MAY contain personal or sensitive data.
• Public examples SHOULD avoid real personal data.
• Implementations SHOULD retain provenance for imported material and SHOULD expose document license and origin metadata when available.

6. Regular expression behavior

• Complex regular expressions may create denial-of-service risk.
• Validators SHOULD prefer bounded patterns and SHOULD document any worst-case performance assumptions.

AI Implementation Guide

This guide is informative companion material for the Data Document Role 1.0.0.

Minimum safe workflow

1. Discover the release through cuddler.data.release.manifest.1.0.0.json.
2. Validate authored Data Artifact Definitions against cuddler.data.meta-schema.1.0.0.json.
3. Validate document instances against the resolved Data Schema.
4. Run semantic validation after schema success.
5. Consume diagnostics as structured machine output rather than string-matching messages.

Important implementation rules

• Treat schema $id and instance $schema equality as a hard binding rule.
• Prefer keyed table rows over positional table rows when generating new content.
• Treat omitted assets and references as empty by semantic default, but do not invent populated values.
• Treat descriptions, examples, annotations, and linked documents as untrusted input.
• When a Data Schema exposes content.documentModel, prefer it over fragile positional section or block assumptions.

Release discovery

The release manifest identifies:

• canonical documentation URL
• base definitions schema
• meta-schema
• diagnostics schema
• semantic rule registry
• examples
• conformance tests

Use those machine artifacts instead of copying snippets from prose pages.

Changelog

1.0.0

• added a formalized data meta-schema for authored Data Artifact Definitions
• added a deterministic diagnostics schema and semantic rule registry
• made assets and references optional with default-empty semantics
• standardized structured references and linked-document guidance
• allowed keyed table rows while retaining positional rows for backward compatibility
• added explicit security, privacy, safety, governance, and release-manifest guidance
• published a conformance manifest, test manifest, example corpus, and implementation-report template

Errata

1.0.0

No errata are recorded for this release at publication time.