Last updated: 3 Mar 2025

publishing-api: Adding a new content schema

Follow these steps to add a new schema:

1. Create a file in formats named after your schema with a jsonnet extension (e.g. for a case_study you'd create ./content_schemas/formats/case_study.jsonnet). The file should have the following contents:

   (import "shared/default_format.jsonnet") + {
   }
   

2. Add the fields required to this file.

   You could use the contents of the formats/_example.jsonnet or other existing schemas as the basis of what to put into the file.

   See this PR for an example of how a new format has previously been added.

3. Add the new format to ./content_schemas/allowed_document_types.yml.

4. Add a set of curated examples. These examples will be validated against the schema and can also be used by the corresponding frontend applications to verify that it can render examples of the schema. These examples should be added to the ./content_schemas/examples/FORMAT_NAME/frontend folder.

5. Generate the corresponding schemas with the following rake task:

   bundle exec rake build_schemas
   

   This step will also validate the examples against the schema.

6. Add the schema to Content Data API.

   To ensure new content schema text can be parsed by Content Data API, it needs to be added to an appropriate Edition Content Parser or a new parser should be created. This ensures that content quality metrics such as word count or reading time are available in Content Data.

   Example of adding a new content schema to the Content Body parser.

   Failing to do so, will cause Etl::Edition::Content::Parser::InvalidSchemaError in Content Data API but basic metrics will still be available in Content Data.