Skip to content
Common ApproachDeveloper Docs

Serialization and encoding

For interchange, CIDS capsules are JSON-LD documents: an array of node objects, each with @context, @type, and @id, linked by IRI references. This section is the syntax profile for published data — what publishers and validators must support.

Formats in scope

Section titled “Formats in scope”
Format Role in this profile
JSON-LD (.json, .jsonld) Primary interchange format for impact data capsules
Turtle (.ttl) Debugging, SHACL reports, ontology and example artifacts
Other RDF serializations Available on ontology and codelist servers; not required for capsule exchange

Context policy

Section titled “Context policy”

Each node object in a capsule SHOULD include a @context that resolves to the published context files:

Multiple contexts: SFF capsules typically use a @context array with both files, as in the published examples.

SHOULD NOT: Rely on undocumented local context fragments for normative properties — consumers may not resolve private context URLs.

Named graphs: Not required for Basic interchange. Tools that emit named graphs must flatten or export in a form validators accept.

See the context file FAQ for how contexts map compact keys to ontology IRIs.

@id and IRI policy

Section titled “@id and IRI policy”
Rule Detail
Every entity node MUST have @id A stable HTTP(S) or other absolute IRI
Minting Publishers mint IRIs under domains they control (e.g. https://example.org/Organization/myorg)
Persistence The same real-world entity SHOULD keep the same @id across exports
Blank nodes Avoid in interchange capsules — importers and validators expect dereferenceable or at least stable IRIs
@type MUST use CIDS (or SFF) class IRIs, typically via context prefix (cids:Organization)

Graph Cast requires callers to supply URIs on create and never mints identifiers on their behalf. That implements this profile rule for the hosted API. See Graph Cast identifiers.

Organization-scoped paths: A common pattern is https://{domain}/{Class}/{slug} (see Examples). No single path template is mandated — consistency within a publisher’s namespace is what matters.

Literals, language, and datatypes

Section titled “Literals, language, and datatypes”
  • Strings — xsd:string for names, descriptions; use @language when providing translated labels where applicable.
  • Dates and times — Use typed literals per context (xsd:date, xsd:dateTime) on reporting periods and timestamps.
  • Numbers — Indicator values use appropriate numeric types; units reference UnitsOfMeasureList or ISO 21972 patterns.
  • Empty strings — "" counts as a value for cardinality; use sh:minLength in SHACL where empty literals must be rejected (see SHACL validation vs. funder requirements and Discussion #165).

Code list references

Section titled “Code list references”

Classification values SHOULD be referenced by concept URI (e.g. https://metadata.un.org/sdg/12), not by display label alone. The hasCode pattern links nodes to code list concepts — see Code lists.

Anti-patterns (non-interoperable)

Section titled “Anti-patterns (non-interoperable)”
Avoid Why
Missing @context on node objects Processors cannot expand to RDF
Relative @id values Breaks merge across capsules
Duplicate @id with different @type Invalid graph merge
Free-text theme names without URI Loses semantic interoperability
Proprietary enums with no published URI Cannot validate or aggregate
Embedding only CSV-equivalent flat rows without links Fails SHACL object property shapes

Hosted import of the same JSON-LD model: Working with capsules.

Section titled “Related”