Skip to main content
Last updated: 5 Jan 2026

publishing-api: How to retire a content schema

Once you're sure that a schema isn't being used any more (ie you've checked that there are no content items of this type, and the publishing app that publishes them has had the relevant code removed), follow these steps to retire it:

  1. Delete the jsonnet file from /content_schemas/formats

  2. Delete any shared definitions that are not used by any of the remaining formats

  3. Delete the schema's folder, if one exists, from /content_schemas/examples

  4. Remove the schema from /content_schemas/allowed_document_types.yml

  5. Validate/rebuild the other schemas with the following rake task:

    bundle exec rake build_schemas

    This step will also validate the examples against the schema.

  6. Delete the GraphQL query for the schema app/graphql/queries/<format_name>.graphql and corresponding tests.

  7. If fields or links_field were only relevant to that schema, delete them in app/graphql/types/edition_type.rb

  8. You may also need to remove the parser from content-data-admin (Example PR)