-
Notifications
You must be signed in to change notification settings - Fork 31
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4781 from alphagov/finder-schema-documentaion
Add guidance for the finder schema
- Loading branch information
Showing
1 changed file
with
44 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| --- | ||
| owner_slack: "#govuk-whitehall-experience-tech" | ||
| title: Finder schema guidance | ||
| parent: "/manual.html" | ||
| layout: manual_layout | ||
| type: learn | ||
| section: Publishing | ||
| --- | ||
|
|
||
| The current schema for finders is defined within the [Publishing API repository](https://github.com/alphagov/publishing-api/blob/main/content_schemas/formats/finder.jsonnet). This document provides a comprehensive line-by-line analysis of the schema and details its functionality. | ||
|
|
||
| | Block | Code | What does it do? | | ||
| | --- | --- | --- | | ||
| | Import Statement|(import "shared/default_format.jsonnet")| Each content schema starts by importing default configuration settings. We introduced Jsonnet precisely because of its support for imports, which helped to significantly reduce duplication across various schema definitions. For a detailed explanation of the configuration options and their functions, refer to the [example](https://github.com/alphagov/publishing-api/blob/main/content_schemas/formats/_example.jsonnet) file. | | ||
| | Document Type Definition|{ document_type: ["finder", "search"],| The document types array allows us to specify which document types can be used with our schema. | | ||
| | Definitions|definitions: {|The "definitions" block is used to define the rules behind individual fields in the schema. | | ||
| | Details|details: {| Placing "details" under "definitions" allows it to be referenced throughout the schema, promoting reusability and consistency. "Details" can reference other parts of "definitions" within itself, enabling a modular approach that simplifies maintenance. Updating any referenced components in "definitions" will automatically apply those changes wherever they are used, including in "details". | | ||
| | |type: "object",| Setting the type property to "object" indicates that details is expected to be a structured object with named properties and specific values. This establishes the basis for creating a complex, nested data structure. | | ||
| | |additionalProperties: false,| Setting additionalProperties to false limits the object to just the properties defined in its schema. This helps keep the details object clean by preventing any extra, undefined properties that could cause issues or errors in how the application handles or shows detailed information. | | ||
| | |required: ["document_noun","facets",]| The required property lists the names of properties that must be included in the details object for it to be valid. | | ||
| | Properties|properties: {| The properties object within details allows us to define specific validation rules for each property. This helps in ensuring that the data conforms to expected formats and constraints. | | ||
| | |beta: {"$ref": "#/definitions/finder_beta",}| The finder_beta property can be a boolean value (true or false) indicating whether the finder is in beta, with true meaning the finder is in beta, false meaning it is not, and null indicating that the beta status is undefined, not applicable, or not set. | | ||
| | |beta_message: {anyOf: [ {type: "string",} ,{type: "null",},],}| The beta_message is an optional string that can contain HTML and be set to null; if the phase is beta, it will be displayed on the beta banner, as detailed [here](https://design-system.service.gov.uk/components/phase-banner/). | | ||
| | |no_index: {type: "boolean",}| The rationale for this property is that some finders are intended to support other content rather than being useful on their own, so instead of hard coding this configuration in finder-frontend, it would be more effective to configure it individually for each finder. | | ||
| | |generic_description: {type: "boolean",}| Adds an option for finders to show a generic filter description like "X publications matched your criteria" instead of generating a sentence based on the selected filters. | | ||
| | |document_noun: {"$ref": "#/definitions/finder_document_noun",},| A required string representing the lowercase singular form of the format used by the Finder. For instance, /cma-cases has a document_noun of case, while /aaib-report has a document_noun of report. This value is used to construct sentences describing the user’s current search. | | ||
| | |default_documents_per_page: {"$ref": "#/definitions/finder_default_documents_per_page",},| An optional integer used to build pagination when querying the Search API. | | ||
| | |logo_path: {type: "string",},| This adds the possibility to add a logo on a finder | | ||
| | |default_order: {"$ref": "#/definitions/finder_default_order",},| An optional string where a minus (-) prefix can be used to sort in descending order here is an [example](https://github.com/alphagov/whitehall/blob/main/lib/finders/case_studies.json#L13); Search API must permit sorting on this field as noted [here](https://github.com/alphagov/search-api/blob/main/lib/parameter_parser/base_parameter_parser.rb#L20). | | ||
| | |sort: {"$ref": "#/definitions/finder_sort",},| Initially added for sorting options in the 'latest documents list,' this feature is now used on the GOV.UK search page and determines the available choices in the 'sort by' dropdown menu, including Most Viewed, Relevance, Updated (Newest), and Updated (Oldest). | | ||
| | |filter: {$ref": "#/definitions/finder_filter",},| The finder_filter object is a structured configuration used to narrow searches within a system. It includes properties such as arrays of strings for categories (e.g., taxonomy, document types, organizations), single strings for document_type and format, and a boolean for has_official_document. To ensure consistency, the object disallows any additional properties. | | ||
| | |open_filter_on_load: {type: "boolean",},| Add the open_filter_on_load property to automatically open filters on mobile when the page loads. This configuration is specific to the Find a Licence (specialist finder) only. | | ||
| | |reject: {"$ref": "#/definitions/finder_reject_filter",},| The finder_reject_filter object defines a filter that excludes documents based on specified criteria. It includes arrays of strings for properties like content purpose, document types, email document supertype, policies, and links. The object does not allow additional properties to ensure strict adherence to the defined criteria. | | ||
| | |facets: {"$ref": "#/definitions/finder_facets",},| The finder_facets array defines the facets available for users to refine their search. Each facet is an object that includes several properties: key, which specifies the field name used for the facet; filterable, indicating whether the facet should be shown to users; display_as_result_metadata, which determines if the facet appears in search result metadata; name, the label for the facet; and type, which defines the UI component and query method, such as checkbox, date, or autocomplete. Additionally, the allowed_values property lists possible values for non-dynamic facets, while combine_mode specifies how the facet combines with others, using options like "and" or "or". Other options control aspects of the facet’s appearance and behavior, such as whether it opens on page load or hides facet tags. | | ||
| | |format_name: {type: "string",},| An optional string, typically a singularized version of the Finder's title, such as "Competition and Markets Authority case" for /cma-cases. While it is generally aligned with the Finder’s title, there are exceptions like "Medical safety alert" for Alerts and recalls for drugs and medical devices. | | ||
| | |label_text: {type: "string",},| Adds a label_text property to rename the label from "Search" to "Keywords" specifically for the licence finder (specialist finder), helping users understand they should enter keywords rather than using it as a general search box. | | ||
| | |show_summaries: {"$ref": "#/definitions/finder_show_summaries",},| A boolean that determines whether summaries for documents should be displayed in the results list, truncating each summary at the end of the first sentence. | | ||
| | |signup_link: {"$ref": "#/definitions/finder_signup_link",},| This property enables finder-frontend to override the default email signup link if necessary. [Here](https://www.gov.uk/drug-safety-update) is an example of where it is used. You can view its implementation in the code [here](https://github.com/alphagov/specialist-publisher/blob/main/lib/documents/schemas/drug_safety_updates.json#L11). | | ||
| | |canonical_link: {type: "boolean",},| An optional boolean that specifies whether a finder frontend page should be indexed by search engines with a canonical link. | | ||
| | |summary: {"$ref": "#/definitions/finder_summary",},| An optional string that is displayed in the header following the metadata. It can include Govspeak and is rendered using the Govspeak component. | | ||
| | Links|(import "shared/base_links.jsonnet")| Here we are importing default configuration settings for links. For a detailed explanation of the configuration options see [here](https://github.com/alphagov/publishing-api/blob/main/content_schemas/formats/shared/base_links.jsonnet) | | ||
| | |related: "",| The related field is set as an empty string, serving as a placeholder for a URL to related content or resources that have not yet been specified. As far as I know, related links can only be added or removed manually through Content Tagger, since the "automatic related links" pipeline has been broken since late 2022 and the associated machine learning service is now [archived](https://github.com/alphagov/govuk-related-links-recommender). | | ||
| | |email_alert_signup: "",| By default, the email alert signup link will direct to base_path/email-signup, where base_path is specified in the Finder object. For instance, for /drug-device-alerts, the default link would be /drug-device-alerts/email-signup. | | ||
| | |available_translations: "",| Available_translations is set to an empty string as a placeholder for a link to access content translations, if any exist. Documents can be available in multiple translations, distinguished by the same content_id but different locale values. Links for an edition will automatically include translations of other editions with the same content_id, including those in the current locale. | |