Skip to main content
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 14 Oct 2024

publishing-api: Changing an existing content schema

When not adding or removing top-level fields

This describes how to add or remove fields that extend the top-level fields defined in default_format.jsonnet. For example, if you wanted to submit an additional field via a form in a publishing app, you might add a field nested within details (a field already defined in default_format.jsonnet).

  1. If you're adding or removing a required field:
    • Update publishing app(s) to provide/stop providing the field
    • If removing a field, update frontend app(s) to no longer access the soon-to-be-removed field
    • Update existing data in Content Store to ensure they conform with the incoming schema changes
  2. Update the relevant schema fragment under content_schemas/formats/<format_name>.jsonnet
    • Add or remove the desired details > properties property
    • If the field is/was required, update the details > required array
  3. If necessary, add, remove or update relevant definition file within content_schemas/formats/shared/definitions to add or remove the definition for the field
  4. Add, remove, or update the relevant example schemas in content_schemas/examples/**/<example_name>.jsonnet
  5. Run rake build_schemas to compile the updated schemas in content_schemas/dist/ and validate the example schemas
  6. Check that all the CI workflows pass. These will verify that the content schemas are compatible with the suite of publishing apps

Non-top-level field examples

When adding or removing top-level fields

This describes how to add or remove top-level fields to the default format. These fields tend to be overridden in .jsonnet schemas that extend default_format.jsonnet. This allows you to, among other things, define a top-level "forbidden" field that should not be provided by consumers of the API, then allow it for schemas further down the chain by marking it as "optional".

  1. If you're adding or removing a required field:
    • Update publishing app(s) to provide/stop providing the field
    • If removing a field, update frontend app(s) to no longer access the soon-to-be-removed field
    • Update existing data in Content Store to ensure they conform with the incoming schema changes
  2. Add/remove the new field in default_format.jsonnet, giving it a status of required, optional, forbidden or null.
  3. Add/remove the new definition file for this field type in content_schemas/formats/shared/definitions. This will need to include a definition for the field and a definition for the optional/required/forbidden status where relevant. This will be read by the format code in the next step
  4. Add a new method named after this field to lib/schema_generator/format.rb to have it written to the generated files. This specifies which definition to use based on the status specified in jsonnet schema
  5. Add a new key to the derived_properties method's hash to read the value in lib/schema_generator/{publisher_content/frontend/notification}_schema_generator.rb when generating the schema
  6. Update any extending jsonnet files to override this value by setting a different status against this field where required, e.g. to mark a default forbidden field as optional at a lower level
  7. Run rake build_schemas to compile the updated schemas in content_schemas/dist/ and validate the example schemas
  8. Check that all the CI workflows pass. These will verify that the content schemas are compatible with the suite of publishing apps

Top-level property examples