json-manifest-reference

This is a reference for the Content Authenticity Initiative (CAI) manifest store JSON structure. It is based on the definition of the manifest store in the C2PA technical specification, but is not exactly the same. The C2PA specification defines a binary structure, but this reference is for the JSON structure that the CAI open source SDKs use to work with manifests.

See the rendered site at https://contentauth.github.io/json-manifest-reference/manifest-reference.

References

Understanding JSON schema: Good explanation of JSON schema.
Jekyll documentation: This repo uses Jekyll and Liquid.
Liquid template language

Implementation

The reference documentation is generated from JSON schema files in the _data directory:

/_data/ManifestStore_schema.json is the canonical file generated from the source code by the dev team.
/_data/ManifestStore_schema_annotated.json is a copy of ManifestStore_schema.json with comments addressed to the dev team added to description fields. This file is used to generate the annotated manifest store reference
/_data/ManifestStore_schema_edited.json is a temporary copy of ManifestStore_schema.json with manual edits to the schema to address some of the issues raised above. These issues should be addressed in the source code and in the schema generation; but until they are, this file is used to generate the reference doc. See below for details.

GitHub workflow

To trigger the GH action, change _data/ManifestStore_schema_edited.json. This will create a PR to update https://opensource.contentauthenticity.org/docs/manifest/manifest-ref/.

Schema manual edits

The schema in ManifestStore_schema_edited.json has the following manual edits:

ResourceStore object definition removed.
Properties of type ResourceStore are removed: Ingredient.resources and Manifest.resources.
Corrected issues with missing or mis-formatted shortlinks in descriptions.
Removed Manifest.claim_generator_hints property.
Removed DateT object and modified the one property that referred to it, Metadata.dateTime to specify a date/time string with ISO 8601 format.
Edited ReviewRating description to use regular markdown link rather than shortlink, which doesn't render properly within fenced HTML paragraph.

How to update the JSON schema

If you don't need to preview (for example if you change is trivial), create and use a branch and then just open a PR. If you're making more extensive changes and want to preview the rendered changes, create a PR using a fork.

To update the schema and see a preview:

Update /_data/ManifestStore_schema.json in your fork.
Find the Pages settings page for your fork, e.g. https://github.com/your_username/c2pa-manifest-reference/settings/pages and enable GitHub Pages. Set:
- Source to Deploy from branch.
- Branch to main / root
- Click Save.
In a couple minutes you will be able to view your Jekyll site at https://your_username.github.io/c2pa-manifest-reference/ (the URL depends on the GH org where you forked the repo).

Checking site status

It's possible to make a change to a page (such as a malformed Liquid directive) that will cause an error, and prevent the site from building. If this occurs, the existing site will be unaffected, and the site will just show the last working version. However, none of the changes in your commit/PR will be visible. You cannot cause such an error with basic markdown, only with Liquid tags or a data file.

To check site status, go to he Pages settings page for your fork. If you see this:

Your site is live at https://your_username.github.io/json-manifest-reference/

Then everything's good!

However, if you see a yellow box that says "There is a problem with the site" and an error message, then you need to figure out what's wrong and fix it before any changes to the site will take effect.

Post-processing notes

JavaScript code converts crate links to anchor links. For example:

crate::Manifest -> #manifest

crate::ManifestStore -> #manifeststore

contentauth/json-manifest-reference