configurable-document-type.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://whitehall-admin.publishing.service.gov.uk/configurable-document-type.schema.json",
  "$defs": {
    "validations": {
      "description": "List of rails validations to apply to properties, mapping to validators in the application. Keys must match available validators.",
      "type": "object",
      "patternProperties": {
        ".*": {
          "type": "object",
          "properties": {
            "attributes": {
              "description": "List of edition fields to validate, with this specific validator.",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "on": {
              "description": "Validation context.",
              "type": "string",
              "enum": ["publish"]
            }
          },
          "additionalProperties": true
        }
      },
      "propertyNames": {
        "enum": [
          "embedded_contacts_exist",
          "length",
          "no_footnotes_allowed",
          "presence",
          "safe_html",
          "valid_internal_path_links",
          "social_media_links"
        ]
      }
    },
    "form_field": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "Display name for the content block."
        },
        "description": {
          "type": "string",
          "description": "Description of the content block's purpose. Usually used for hint text."
        },
        "required": {
          "type": "boolean",
          "description": "Whether or not the form value is required"
        },
        "attribute_path": {
          "type": "array",
          "description": "The path of the active record attribute this field controls. For JSON attributes this may have multiple items",
          "items": {
            "type": "string"
          }
        },
        "block": {
          "type": "string",
          "description": "Identifier for a content block. Maps to a specific block class.",
          "enum": [
            "default_array",
            "default_date",
            "default_object",
            "default_string",
            "govspeak",
            "default_select",
            "select_with_search_tagging",
            "ordered_select_with_search_tagging"
          ]
        },
        "fields": {
          "type": "object",
          "patternProperties": {
            ".*": {
              "$ref": "#/$defs/form_field"
            }
          }
        },
        "translatable": {
          "description": "Determines whether or not the field's value can be translated for different locales",
          "type": "boolean"
        },
        "experimental": {
          "description": "When true, only renders the field if the configurable_document_types feature flag is enabled",
          "type": "boolean"
        },
        "options": {
          "type": "array",
          "description": "List of options for select inputs.",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "value": {
                "type": "string"
              }
            },
            "required": ["label", "value"]
          }
        },
        "blank_option_label": {
          "type": "string",
          "description": "Text to display for the blank/default option in a select input."
        },
        "container": {
          "description": "The option container to be used in the select_with_search_tagging_block",
          "type": "string",
          "enum": [
            "alternative_format_providers",
            "detailed_guides",
            "ministerial_role_appointments",
            "organisations",
            "role_appointments",
            "roles",
            "statistical_data_sets",
            "topical_event_documents",
            "topical_events",
            "world_locations",
            "worldwide_organisations"
          ]
        },
        "size": {
          "type": "number",
          "description": "The number of items in an array field"
        },
        "add_another_button_text": {
          "type": "string",
          "description": "Text to display for the 'Add another' button in default_array block. If empty, it defaults to 'Add another'."
        }
      },
      "required": ["title", "block", "attribute_path", "translatable"],
      "additionalProperties": false
    },
    "block_attributes": {
      "type": "object",
      "description": "Map of content block attribute definitions (minimal schema).",
      "patternProperties": {
        ".*": { "$ref": "#/$defs/block_attribute" }
      },
      "additionalProperties": false
    },
    "block_attribute": {
      "type": "object",
      "description": "Minimal schema information for a single content block attribute.",
      "properties": {
        "type": {
          "type": "string",
          "description": "Data type for the content block. Should map to an active record type, with the exception of the object type.",
          "enum": ["string", "integer", "date", "array"]
        },
        "attributes": {
          "description": "For array types, defines the schema of each array item using the same minimal attribute format.",
          "$ref": "#/$defs/block_attributes"
        }
      },
      "required": ["type"],
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "properties": { "type": { "const": "array" } },
            "required": ["type"]
          },
          "then": {
            "properties": {
              "attributes": { "$ref": "#/$defs/block_attributes" }
            }
          },
          "else": {
            "not": {
              "required": ["attributes"]
            }
          }
        }
      ]
    }
  },
  "title": "Configurable Document Type",
  "description": "Schema for a configurable document type in Whitehall",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^[a-z_]*$",
      "description": "Unique identifier for the document type. This value is stored in the edition's configurable_document_type column."
    },
    "title": {
      "type": "string",
      "description": "Human-readable name for the document type, used in the admin interface."
    },
    "description": {
      "type": "string",
      "description": "A description of the document type's purpose and intended use."
    },
    "schema": {
      "type": "object",
      "description": "Defines the content structure for the document type. Each property represents a content block.",
      "properties": {
        "attributes": {
          "$ref": "#/$defs/block_attributes",
          "description": "Alternative to `properties`, defining content blocks with minimal schema information."
        },
        "validations": {
          "$ref": "#/$defs/validations"
        },
        "headings_from": {
          "type": "array",
          "description": "Array of content block names, from which to extract headings, used to generate the table of contents for the rendered document. Headings are sent to publishing API as part of the `details` hash.",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "forms": {
      "type": "object",
      "description": "Defines the content structure for the document type. Each property represents a content block.",
      "required": ["documents"],
      "properties": {
        "documents": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "fields": {
              "type": "object",
              "description": "Fields/content blocks for the document, each with its own schema.",
              "patternProperties": {
                ".*": {
                  "$ref": "#/$defs/form_field"
                }
              }
            }
          }
        }
      },
      "additionalProperties": {
        "type": "object",
        "description": "Definition of a group of form fields to group.",
        "properties": {
          "dynamic": {
            "type": "boolean",
            "description": "Determines if the field should have a tab generated dynamically"
          },
          "label": {
            "type": "string",
            "description": "Text to display as the label for the group of fields. Shown on the tab in the admin interface."
          },
          "fields": {
            "type": "object",
            "description": "Fields/content blocks for this form, each with its own schema.",
            "patternProperties": {
              ".*": {
                "$ref": "#/$defs/form_field"
              }
            }
          },
          "linked_to": {
            "type": "string",
            "description": "Named route this tab links to. Mutually exclusive with fields. Used for tabs whose UI is owned by an existing controller (attachments, features, images).",
            "enum": [
              "edition_attachments",
              "edition_features",
              "edition_images"
            ]
          }
        },
        "oneOf": [
          { "required": ["fields"] },
          { "required": ["linked_to"] }
        ]
      }
    },
    "presenters": {
      "type": "object",
      "description": "Defines how content blocks map to publishing API presenters and formats.",
      "properties": {
        "publishing_api": {
          "type": "object",
          "properties": {
            "details": {
              "type": "object",
              "description": "Mapping of schema attributes to their respective publishing API details formats.",
              "patternProperties": {
                ".*": {
                  "type": "string",
                  "description": "The format to use for the content block when presenting to the Publishing API.",
                  "enum": [
                    "govspeak",
                    "rfc3339_date",
                    "image",
                    "raw",
                    "social_media_links"
                  ]
                }
              },
              "propertyNames": {
                "type": "string",
                "description": "Attribute to be included in the presenter payload. Must match an existing attribute defined in the schema."
              }
            },
            "links": {
              "description": "The builder methods to use for the links object when presenting to the Publishing API.",
              "type": "array",
              "items": {
                "type": "string",
                "description": "The builder methods to use for populating the links object when presenting to the Publishing API.",
                "enum": [
                  "ministerial_role_appointments",
                  "topical_events",
                  "world_locations",
                  "organisations",
                  "worldwide_organisations",
                  "government"
                ]
              }
            }
          },
          "additionalProperties": false,
          "required": ["details", "links"]
        }
      },
      "additionalProperties": false,
      "required": ["publishing_api"]
    },
    "settings": {
      "type": "object",
      "description": "A list of configurations to enable certain edition behaviours.",
      "properties": {
        "base_path_prefix": {
          "type": "string",
          "description": "URL prefix for where documents of this type are published. E.g. /government/history.",
          "pattern": "^\/[\/.a-zA-Z0-9-]+$",
          "x-error": {
            "pattern": "string at `settings/base_path_prefix` is not a valid URL"
          }
        },
        "configurable_document_group": {
          "type": "string",
          "description": "Optional grouping for document types. Used for categorisation in the admin interface, including search filters. Typically matches the `publishing_api_schema_name`. For example, both `news_story` and `government_response` types would have the group `news_article`.",
          "enum": [
            "news_article"
          ]
        },
        "publishing_api_schema_name": {
          "type": "string",
          "description": "Name of the schema in the Publishing API for this document type. Different types might share the same schema name. For example, `news_story` and `government_response` types both use the `news_article` schema.",
          "enum": [
            "history",
            "topical_event",
            "news_article",
            "case_study"
          ]
        },
        "publishing_api_document_type": {
          "type": "string",
          "description": "Document type name in the Publishing API.",
          "enum": [
            "government_response",
            "news_story",
            "press_release",
            "world_news_story",
            "history",
            "topical_event",
            "case_study"
          ]
        },
        "rendering_app": {
          "type": "string",
          "description": "The frontend application responsible for rendering this document type.",
          "enum": [
            "frontend",
            "collections"
          ]
        },
        "images": {
          "type": "object",
          "description": "Whether users can upload images for this document type. When enabled, it renders the Images tab.",
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Whether users can upload images for this document type. When enabled, it renders the Images tab."
            },
            "usages": {
              "type": "object",
              "patternProperties": {
                ".*": {
                  "type": "object",
                  "required": ["kinds", "multiple", "caption_enabled"],
                  "properties": {
                    "label": {
                      "type": "string",
                      "description": "The human-friendly label for the usage"
                    },
                    "multiple": {
                      "type": "boolean",
                      "description": "Whether users can upload multiple images of this image kind"
                    },
                    "caption_enabled": {
                      "type": "boolean",
                      "description": "Whether the caption field is shown for this image usage. Defaults to true if not specified."
                    },
                    "kinds": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "The name of the image kind",
                        "enum": [
                          "default",
                          "topical_event_logo",
                          "topical_event_header",
                          "landing_page_image",
                          "hero_desktop",
                          "hero_tablet",
                          "hero_mobile"
                        ]
                      },
                      "minLength": 1,
                      "additionalProperties": false
                    }
                  }
                }
              },
              "propertyNames": {
                "enum": [
                  "govspeak_embed",
                  "plan_for_change_landing_page",
                  "hero",
                  "header",
                  "logo",
                  "sidebar",
                  "lead"
                ]
              },
              "minLength": 1,
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        "send_change_history": {
          "type": "boolean",
          "description": "Whether to send change history to the Publishing API. The change history will allow users to see major change updates to the document. Most editionable types should have this enabled."
        },
        "organisations": {
          "type": ["array", "null"],
          "description": "Array of organisation content IDs allowed to use this type, or null to allow all organisations.",
          "items": {
            "type": "string"
          }
        },
        "backdating_enabled": {
          "type": "boolean",
          "description": "Whether backdating is allowed for this document type. This is required for documents representing past printed papers or documents from other digital sources outside Whitehall."
        },
        "history_mode_enabled": {
          "type": "boolean",
          "description": "Whether history mode is enabled for this document type. This controls whether the document can be marked as political."
        },
        "file_attachments_enabled": {
          "type": "boolean",
          "description": "Whether file attachments are allowed for this document type. When enabled, it renders the Attachments tab."
        },
        "translations_enabled": {
          "type": "boolean",
          "description": "Whether translations are supported for this document type."
        }
      },
      "required": [
        "base_path_prefix",
        "publishing_api_schema_name",
        "publishing_api_document_type",
        "rendering_app",
        "images",
        "send_change_history",
        "organisations",
        "backdating_enabled",
        "history_mode_enabled",
        "translations_enabled"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "key",
    "schema",
    "forms",
    "presenters",
    "settings",
    "title",
    "description"
  ],
  "if": {
    "properties": {
      "settings": {
        "properties": {
          "images": {
            "properties": {
              "enabled": { "const": false }
            }
          }
        }
      }
    }
  },
  "then": {
    "properties": {
      "forms": {
        "properties": {
          "images": {
            "maxProperties": 0,
            "x-error": {
              "maxProperties": "forms/images cannot be defined if settings/images/enabled is `false`"
            }
          }
        }
      }
    }
  }
}