Merge pull request #115 from hmrc/API-7937

API-7937- Unify api-definition-schema.json and api-definition.md
hmrc · Oct 29, 2024 · b9afda5 · b9afda5
2 parents f7534c8 + 1644286
commit b9afda5
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 44 deletions.
diff --git a/app/resources/api-definition-schema.json b/app/resources/api-definition-schema.json
@@ -182,7 +182,10 @@
                               },
                               "UrlValidationRule": {
                                 "description": "A URL Rule to validate a URL field.",
-                                "type": "object"
+                                "type": "object",
+                                "properties": {
+
+                                }
                               }
                             }
                           }
@@ -198,7 +201,7 @@
                           "type": "object",
                           "properties": {
                             "read": {
-                              "description": "Who going to have Read Access to the value of this Subscription Field",
+                              "description": "Who has Read Access to the value of this Subscription Field",
                               "type": "string",
                               "enum": [
                                 "anyone",
@@ -207,7 +210,7 @@
                               ]
                             },
                             "write": {
-                              "description": "Who going to have Write Access to the value of this Subscription Field",
+                              "description": "Who has Write Access to the value of this Subscription Field",
                               "type": "string",
                               "enum": [
                                 "anyone",

diff --git a/docs/api-definition.md b/docs/api-definition.md
@@ -4,90 +4,85 @@ Generated from [JSON schema](app/resources/api-definition-schema.json)
 HMRC API definition. See [JSON definition]
 
 | Name | Type | Required | Values | Description |
-| --- | --- |----------| --- | --- |
+| --- | --- | --- | --- | --- |
 | `api` | _object_ | Required | [api](#api) | Details of the API |
 ### `api`
 Details of the API
 
 | Name | Type | Required | Values | Description |
 | --- | --- | --- | --- | --- |
 | `name` | _string_ | Required | ^[A-Z]{1}.*$ | The name for the API (title case i.e. Individual Benefits, not Individual benefits). |
-| `versions` | _object[]_ | Required | [versions](#versions) | A list of the different versions of the API |
+| `description` | _string_ | Required |  | The description for the API |
 | `context` | _string_ | Required | ^[a-z]+[a-z/\-]{4,}$ | The unique context for the API. This should be consistent with the HMRC Domain Model. See [API Domain Model](https://confluence.tools.tax.service.gov.uk/display/ApiPlatform/HMRC%27s+API+Domain+Model) |
 | `isTestSupport` | _boolean_ | Optional | False (default) | Categorises the API as being a Test Support API |
 | `categories` | _string[]_ | Optional | EXAMPLE<br>AGENTS<br>BUSINESS_RATES<br>CHARITIES<br>CONSTRUCTION_INDUSTRY_SCHEME<br>CORPORATION_TAX<br>CUSTOMS<br>ESTATES<br>HELP_TO_SAVE<br>INCOME_TAX_MTD<br>LIFETIME_ISA<br>MARRIAGE_ALLOWANCE<br>NATIONAL_INSURANCE<br>PAYE<br>PENSIONS<br>PRIVATE_GOVERNMENT<br>RELIEF_AT_SOURCE<br>SELF_ASSESSMENT<br>STAMP_DUTY<br>TRUSTS<br>VAT<br>VAT_MTD<br>OTHER | The list of service groups the API will be categorised by. |
-| `description` | _string_ | Required |  | The description for the API |
+| `versions` | _object[]_ | Required | [versions](#versions) | A list of the different versions of the API |
 ### `versions`
 Details of an API version
 
 | Name | Type | Required | Values | Description |
 | --- | --- | --- | --- | --- |
+| `endpoints` | _None_ | Optional |  | DEPRECATED |
+| `version` | _string_ | Required | ^[0-9\.P]+$ | The version number. Eg 1.0 |
 | `status` | _string_ | Required | PROTOTYPED<br>PUBLISHED<br>ALPHA<br>BETA<br>STABLE<br>DEPRECATED<br>RETIRED | The current lifecycle status. PROTOTYPED and PUBLISHED should not be used. See [Lifecycle] |
-| `fieldDefinitions` | _object[]_ | Optional | [fielddefinitions](#fieldDefinitions) | A list of subscription fields for this API version. |
-| `access` | _object_ | Optional | [access](#access) | Used to indicate whether this API version is public or private. If absent, the API defaults to public. See [Access] |
 | `endpointsEnabled` | _boolean_ | Optional | True (default) | Whether the endpoints are shown as available on the DevHub documentation page. This does not effect if the API can actually be used / called. This value MUST be false if the API versions status is ALPHA |
-| `version` | _string_ | Required | ^[0-9\.P]+$ | The version number. Eg 1.0 |
-| `endpoints` | _None_ | Optional |  | DEPRECATED |
+| `access` | _object_ | Optional | [access](#access) | Used to indicate whether this API version is public or private. If absent, the API defaults to public. See [Access] |
+| `fieldDefinitions` | _object[]_ | Optional | [fielddefinitions](#fieldDefinitions) | A list of subscription fields for this API version. |
 ### `access`
 Used to indicate whether this API version is public or private. If absent, the API defaults to public. See [Access]
 
 | Name | Type | Required | Values | Description |
 | --- | --- | --- | --- | --- |
-| `isTrial` | _boolean_ | Optional |  | Whether this API version is a private trial |
 | `type` | _string_ | Required | PUBLIC<br>PRIVATE | Whether the API version is publicly available or only for private use. |
-
+| `whitelistedApplicationIds` | _string[]_ | Optional |  | DEPRECATED. This is no longer used. Please contact SDST to add applications to the allowlist. |
+| `isTrial` | _boolean_ | Optional |  | Whether this API version is a private trial |
 ### `fieldDefinitions`
 Details a subscription field used by this API. If you would like to use subscription fields you should talk to the API Platform team first #team-api-platform-sup.
 
 | Name | Type | Required | Values | Description |
 | --- | --- | --- | --- | --- |
-| `shortDescription` | _string_ | Optional |  | A short description that is displayed on the API metadata page |
-| `validation` | _object_ | Optional | [validation](#validation) | Rules to validate the value of the Field Definition |
-| `hint` | _string_ | Optional |  | Hint text to display to users to help them provide a correct value for this field.  If left blank the description will be used instead |
-| `type` | _string_ | Required | URL<br>SecureToken<br>STRING<br>PPNSField | The type of value expected for this field |
 | `name` | _string_ | Required | ^[a-zA-Z]*$ | The internal identifier for this field |
 | `description` | _string_ | Required |  | The description that will be shown to users for this field |
-| `access` | _object_ | Optional | [access](#fieldaccess) | Access control for the value of this Subscription Field |
-
-<a name="fieldaccess"></a>
-
-### `access`
-Access control for the value of this Subscription Field. See [Access](#fieldaccess)
+| `type` | _string_ | Required | URL<br>SecureToken<br>STRING<br>PPNSField | The type of value expected for this field |
+| `hint` | _string_ | Optional |  | Hint text to display to users to help them provide a correct value for this field |
+| `shortDescription` | _string_ | Optional |  | A short description that is displayed on the API metadata page |
+| `validation` | _object_ | Optional | [validation](#validation) | Contains Rules to validate the value of the Field Definition. |
+| `access` | _object_ | Optional | [access](#access) | Access control for the value of this Subscription Field |
+### `validation`
+Contains Rules to validate the value of the Field Definition.
 
 | Name | Type | Required | Values | Description |
 | --- | --- | --- | --- | --- |
-| `devhub` | _object_ | Optional | [devhub](#devhub)  | Read / Write Access control within Developer Hub for the Subscription Field. |
-
-### `devhub`
-The Regular Expression to validate the field value. See [DevHub]
+| `errorMessage` | _string_ | Optional |  | The error message that will be shown to users if this field is invalid. |
+| `rules` | _object[]_ | Optional | [rules](#rules) | An array of Validation Rules to validate the field's value. |
+### `rules`
+A Validation Rule to validate the field value.
 
 | Name | Type | Required | Values | Description |
 | --- | --- | --- | --- | --- |
-| `read` | _string_ | Optional | anyone<br>adminOnly<br>noOne | The required Read Access level for the Subscription Field. This defaults to anyone Access level |
-| `write` | _string_ | Optional | anyone<br>adminOnly<br>noOne | The required Write Access level for the Subscription Field. This defaults to anyone Access level |
-
-### `validation`
-Contains Rules to validate the value of the Field Definition. See [Validation]
+| `RegexValidationRule` | _object_ | Optional | [regexvalidationrule](#RegexValidationRule) | A Regex Rule to validate the field value. |
+| `UrlValidationRule` | _object_ | Optional | [urlvalidationrule](#UrlValidationRule) | A URL Rule to validate a URL field. |
+### `RegexValidationRule`
+A Regex Rule to validate the field value.
 
 | Name | Type | Required | Values | Description |
 | --- | --- | --- | --- | --- |
-| `errorMessage` | _string_ | Required |  | The error message that will be shown to users if this field is invalid. |
-| `rules` | _object[]_ | Required | [rules](#rules) | An array of Validation Rules to validate the field's value. |
-
-### `rules`
-Details of a Validation Rule. This currently only supports Regular Expression Rules. See [Rules]
+| `regex` | _string_ | Optional |  | Regex to validate the field value. |
+### `UrlValidationRule`
+A URL Rule to validate a URL field.
 
 | Name | Type | Required | Values | Description |
 | --- | --- | --- | --- | --- |
-| `RegexValidationRule` | _object_ | Optional | [RegexValidationRule](#RegexValidationRule) | A Regular Expression Rule |
-| `UrlValidationRule` | _object_ | Optional | [UrlValidationRule](#UrlValidationRule) | A URL Validation Rule |
-
-### `RegexValidationRule`
-The Regular Expression to validate the field value. See [RegexValidationRule]
+### `access`
+Access control for the value of this Subscription Field
 
 | Name | Type | Required | Values | Description |
 | --- | --- | --- | --- | --- |
-| `regex` | _string_ | Required |  | A Regular Expression |
+| `devhub` | _object_ | Optional | [devhub](#devhub) | Access control within Developer Hub for the value of this Subscription Field |
+### `devhub`
+Access control within Developer Hub for the value of this Subscription Field
 
-### `UrlValidationRule`
-This is an empty object to specify that URL Validation applies to the field's value. See [UrlValidationRule]
+| Name | Type | Required | Values | Description |
+| --- | --- | --- | --- | --- |
+| `read` | _string_ | Optional | anyone<br>adminOnly<br>noOne | Who has Read Access to the value of this Subscription Field |
+| `write` | _string_ | Optional | anyone<br>adminOnly<br>noOne | Who has Write Access to the value of this Subscription Field |
diff --git a/run_all_tests.sh b/run_all_tests.sh
@@ -2,3 +2,4 @@
 
 export SBT_OPTS="-XX:MaxMetaspaceSize=1G"
 sbt pre-commit
+./generate-api-definition-docs.py app/resources/api-definition-schema.json > docs/api-definition.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,3 +2,4 @@

		export SBT_OPTS="-XX:MaxMetaspaceSize=1G"
		sbt pre-commit
		./generate-api-definition-docs.py app/resources/api-definition-schema.json > docs/api-definition.md