Skip to content
Open Intent Schema

7. Serialization

This section is normative.

JSON is the canonical format. Records MUST be valid UTF-8 JSON (RFC 8259) and MUST validate against the JSON Schema in Appendix B.

  • YAML for authoring: producers MAY author records in YAML 1.2, for example intents kept in a repository. YAML MUST be converted to JSON without loss before validation, digest computation or exchange. YAML features without a JSON equivalent, such as tags, merge keys or non-string keys, MUST NOT be used.
  • Strict core, open extensions: consumers MUST reject records whose ois major version they do not support. Within a supported major version, consumers MUST accept unknown top-level fields added by a later minor version, MUST NOT remove them when storing or forwarding the record, and MUST reject fields that the declared version itself does not define. During 0.x, each minor version counts as its own major version. Unknown entries inside extensions MUST be ignored (section 10.1).
  • Timestamps: producers SHOULD write timestamps in UTC.
  • Media type: application/vnd.ois+json is proposed for exchange. It is not yet registered with IANA (Appendix C).
  • File names: records SHOULD use the extension .ois.json, or .ois.yaml when authored in YAML.

When records are kept in a repository, this layout is RECOMMENDED:

Path Content
.ois/intents/ Intent records, one file per intent version
.ois/actors/ Actor records
.ois/artifacts/ Artifact records
.ois/evidence/ Evidence records
.ois/decisions/ Decision records

Evidence and decisions MAY instead be stored outside the repository, for example in an artifact store, and exchanged as bundles.