Update JSON Schema version to Draft 2020-12

[James Chapman (JC-wk)]

Resolves #4795

What is being addressed

Various schema are currently in use, this aligns templates to the latest.
Minor spelling and naming issues are also fixed
fixes issues in template schema docs

How is this addressed

• Changed "$schema" from "http://json-schema.org/draft-07/schema" to "https://json-schema.org/draft/2020-12/schema" in:

  • api_app/schemas/workspace_service.json
  • api_app/tests_ma/conftest.py
  • api_http_requests/API Template Modifying Endpoints.http
  • api_http_requests/API User Journey.http
  • docs/schemas/operation.json
  • docs/schemas/resource-assignment.json
  • docs/schemas/resource.json
  • docs/tre-templates/pipeline-templates/overview.md
  • docs/tre-workspace-authors/authoring-workspace-templates.md
  • e2e_tests/test.http
  • e2e_tests/test_workspace_service_templates.py
  • templates/shared_services/admin-vm/template_schema.json
  • templates/shared_services/airlock_notifier/template_schema.json
  • templates/shared_services/certs/template_schema.json
  • templates/shared_services/cyclecloud/template_schema.json
  • templates/shared_services/databricks-auth/template_schema.json
  • templates/shared_services/firewall/template_schema.json
  • templates/shared_services/gitea/template_schema.json
  • templates/shared_services/sonatype-nexus-vm/template_schema.json
  • templates/workspace_services/azureml/template_schema.json
  • templates/workspace_services/azuresql/template_schema.json
  • templates/workspace_services/databricks/template_schema.json
  • templates/workspace_services/guacamole/template_schema.json
  • templates/workspaces/airlock-import-review/template_schema.json
  • templates/workspaces/base/template_schema.json
  • templates/workspaces/unrestricted/template_schema.json

• removed $id on individual properties as these are not required (added docs to explain)

• Updated version numbers for several shared services and workspace templates to reflect new changes.

• Update documentation

• Update CHANGELOG.md

• Increment template versions

[github-actions]

Unit Test Results

753 tests   753 ✅  13s ⏱️
  1 suites    0 💤
  1 files      0 ❌

Results for commit acfe17e.

♻️ This comment has been updated with latest results.

[Copilot]

Pull request overview

Updates Azure TRE’s template JSON Schemas and documentation to standardize on JSON Schema Draft 2020-12, aligning templates/docs/examples with newer keywords (e.g., unevaluatedProperties) and keeping template/API versions in sync.

Changes:

• Switched $schema declarations across templates, API schema files, tests, and docs to https://json-schema.org/draft/2020-12/schema.
• Bumped multiple template bundle versions (Porter version:) to reflect the schema change.
• Updated documentation and HTTP/e2e examples that embed JSON schema snippets.

Reviewed changes

Copilot reviewed 71 out of 71 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
templates/workspaces/unrestricted/template_schema.json	Updates workspace template schema $schema to Draft 2020-12.
templates/workspaces/unrestricted/porter.yaml	Patch bump for unrestricted workspace bundle version.
templates/workspaces/base/template_schema.json	Updates workspace base schema $schema to Draft 2020-12.
templates/workspaces/base/porter.yaml	Patch bump for base workspace bundle version.
templates/workspaces/airlock-import-review/template_schema.json	Updates airlock import review workspace $schema to Draft 2020-12.
templates/workspaces/airlock-import-review/porter.yaml	Patch bump for airlock import review workspace bundle version.
templates/workspace_services/openai/template_schema.json	Updates OpenAI service schema $schema to Draft 2020-12.
templates/workspace_services/openai/porter.yaml	Patch bump for OpenAI workspace service bundle version.
templates/workspace_services/ohdsi/template_schema.json	Updates OHDSI service schema $schema to Draft 2020-12.
templates/workspace_services/ohdsi/porter.yaml	Patch bump for OHDSI workspace service bundle version.
templates/workspace_services/mysql/template_schema.json	Updates MySQL service schema $schema to Draft 2020-12.
templates/workspace_services/mysql/porter.yaml	Patch bump for MySQL workspace service bundle version.
templates/workspace_services/health-services/template_schema.json	Updates health services schema $schema to Draft 2020-12.
templates/workspace_services/health-services/porter.yaml	Patch bump for health services workspace service bundle version.
templates/workspace_services/guacamole/user_resources/guacamole-azure-windowsvm/template_schema.json	Updates Guacamole Windows VM user resource schema $schema to Draft 2020-12.
templates/workspace_services/guacamole/user_resources/guacamole-azure-windowsvm/porter.yaml	Patch bump for Guacamole Windows VM user resource bundle version.
templates/workspace_services/guacamole/user_resources/guacamole-azure-linuxvm/template_schema.json	Updates Guacamole Linux VM user resource schema $schema to Draft 2020-12.
templates/workspace_services/guacamole/user_resources/guacamole-azure-linuxvm/porter.yaml	Patch bump for Guacamole Linux VM user resource bundle version.
templates/workspace_services/guacamole/user_resources/guacamole-azure-import-reviewvm/template_schema.json	Updates Guacamole import review VM user resource schema $schema to Draft 2020-12.
templates/workspace_services/guacamole/user_resources/guacamole-azure-import-reviewvm/porter.yaml	Patch bump for Guacamole import review VM user resource bundle version.
templates/workspace_services/guacamole/user_resources/guacamole-azure-export-reviewvm/template_schema.json	Updates Guacamole export review VM user resource schema $schema to Draft 2020-12.
templates/workspace_services/guacamole/user_resources/guacamole-azure-export-reviewvm/porter.yaml	Patch bump for Guacamole export review VM user resource bundle version.
templates/workspace_services/guacamole/template_schema.json	Updates Guacamole workspace service schema $schema to Draft 2020-12.
templates/workspace_services/guacamole/porter.yaml	Patch bump for Guacamole workspace service bundle version.
templates/workspace_services/gitea/template_schema.json	Updates Gitea workspace service schema $schema to Draft 2020-12.
templates/workspace_services/gitea/porter.yaml	Patch bump for Gitea workspace service bundle version.
templates/workspace_services/databricks/template_schema.json	Updates Databricks workspace service schema $schema to Draft 2020-12.
templates/workspace_services/databricks/porter.yaml	Patch bump for Databricks workspace service bundle version.
templates/workspace_services/azuresql/template_schema.json	Updates Azure SQL workspace service schema $schema to Draft 2020-12.
templates/workspace_services/azuresql/porter.yaml	Patch bump for Azure SQL workspace service bundle version.
templates/workspace_services/azureml/user_resources/aml_compute/template_schema.json	Updates AML compute user resource schema $schema to Draft 2020-12.
templates/workspace_services/azureml/user_resources/aml_compute/porter.yaml	Patch bump for AML compute user resource bundle version.
templates/workspace_services/azureml/template_schema.json	Updates AzureML workspace service schema $schema to Draft 2020-12.
templates/workspace_services/azureml/porter.yaml	Patch bump for AzureML workspace service bundle version.
templates/shared_services/sonatype-nexus-vm/template_schema.json	Updates Nexus shared service schema $schema to Draft 2020-12.
templates/shared_services/sonatype-nexus-vm/porter.yaml	Patch bump for Nexus shared service bundle version.
templates/shared_services/gitea/template_schema.json	Updates shared Gitea schema $schema to Draft 2020-12.
templates/shared_services/gitea/porter.yaml	Patch bump for shared Gitea bundle version.
templates/shared_services/firewall/template_schema.json	Updates firewall shared service schema $schema to Draft 2020-12.
templates/shared_services/firewall/porter.yaml	Patch bump for firewall shared service bundle version.
templates/shared_services/databricks-auth/template_schema.json	Updates databricks-auth shared service schema $schema to Draft 2020-12.
templates/shared_services/databricks-auth/porter.yaml	Patch bump for databricks-auth shared service bundle version.
templates/shared_services/cyclecloud/template_schema.json	Updates CycleCloud shared service schema $schema to Draft 2020-12.
templates/shared_services/cyclecloud/porter.yaml	Patch bump for CycleCloud shared service bundle version.
templates/shared_services/certs/template_schema.json	Updates certs shared service schema $schema to Draft 2020-12.
templates/shared_services/certs/porter.yaml	Patch bump for certs shared service bundle version.
templates/shared_services/airlock_notifier/template_schema.json	Updates airlock notifier schema $schema to Draft 2020-12.
templates/shared_services/airlock_notifier/porter.yaml	Patch bump for airlock notifier shared service bundle version.
templates/shared_services/admin-vm/template_schema.json	Updates admin-vm shared service schema $schema to Draft 2020-12.
templates/shared_services/admin-vm/porter.yaml	Patch bump for admin-vm shared service bundle version.
e2e_tests/test.http	Updates embedded $schema in HTTP test payload to Draft 2020-12.
e2e_tests/test_workspace_service_templates.py	Updates embedded $schema in e2e test payload to Draft 2020-12.
docs/tre-workspace-authors/authoring-workspace-templates.md	Documents Draft 2020-12 as the template schema standard.
docs/tre-templates/pipeline-templates/overview.md	Updates example $schema value to Draft 2020-12.
docs/schemas/resource.json	Updates docs schema $schema to Draft 2020-12.
docs/schemas/resource-assignment.json	Updates docs schema $schema to Draft 2020-12.
docs/schemas/operation.json	Updates docs schema $schema to Draft 2020-12.
api_http_requests/API User Journey.http	Updates embedded $schema values in request examples to Draft 2020-12.
api_http_requests/API Template Modifying Endpoints.http	Updates embedded $schema values in request examples to Draft 2020-12.
api_app/tests_ma/conftest.py	Updates test fixtures’ $schema values to Draft 2020-12.
api_app/schemas/workspace.json	Updates API schema $schema to Draft 2020-12.
api_app/schemas/workspace_service.json	Updates API schema $schema to Draft 2020-12.
api_app/schemas/user_resource.json	Updates API schema $schema to Draft 2020-12.
api_app/schemas/shared_service.json	Updates API schema $schema to Draft 2020-12.
api_app/schemas/azuread.json	Updates API schema $schema to Draft 2020-12.
api_app/models/schemas/workspace_template.py	Updates OpenAPI example $schema to Draft 2020-12.
api_app/models/schemas/workspace_service_template.py	Updates OpenAPI example $schema to Draft 2020-12.
api_app/models/schemas/user_resource_template.py	Updates OpenAPI example $schema to Draft 2020-12.
api_app/models/schemas/shared_service_template.py	Updates OpenAPI example $schema to Draft 2020-12.
api_app/_version.py	Bumps API version to 0.26.0.

[Copilot]

Pull request overview

Copilot reviewed 71 out of 71 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (8)

templates/workspaces/unrestricted/template_schema.json:3

• The schema "$id" points to the base workspace schema URL, but this file is the unrestricted workspace schema. This makes the schema identifier non-unique and can break $ref resolution/caching in validators.
  templates/workspace_services/openai/template_schema.json:3
• The schema "$id" points to the SQL workspace service schema URL, but this file is the OpenAI workspace service schema. Using the wrong $id can cause incorrect schema identification and $ref resolution issues.
  templates/workspace_services/mysql/template_schema.json:3
• The schema "$id" points to the SQL workspace service schema URL, but this file is the MySQL workspace service schema. The $id should uniquely identify this schema.
  templates/workspace_services/gitea/template_schema.json:3
• The schema "$id" currently points to the Guacamole workspace service schema URL instead of the Gitea schema. This makes the schema identifier misleading/non-unique.
  templates/shared_services/cyclecloud/template_schema.json:3
• The schema "$id" points to a Guacamole user resource schema URL, but this file is the CycleCloud shared service schema. The $id should be updated to the canonical CycleCloud schema URL.

  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/microsoft/AzureTRE/templates/workspace_services/guacamole/user_resources/guacamole-azure-linuxvm/template_schema.json",

templates/workspace_services/health-services/template_schema.json:3

• The schema "$id" URL uses "healthcare_services" but the template lives under "health-services". Keeping the $id aligned with the actual canonical path avoids confusion and makes schema identifiers consistent across templates.
  templates/workspaces/airlock-import-review/template_schema.json:3
• The schema "$id" uses "airlock_import_review" but the template directory name is "airlock-import-review". For consistency (and to avoid broken canonical links), the $id should match the actual path.
  docs/tre-workspace-authors/authoring-workspace-templates.md:86
• The fenced ```json example is not valid JSON (it’s missing the surrounding braces). This can confuse readers and some renderers/linters.

```json
"$schema": "https://json-schema.org/draft/2020-12/schema"

</details>

[Copilot]

Pull request overview

Copilot reviewed 71 out of 71 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

docs/tre-workspace-authors/authoring-workspace-templates.md:86

• The JSON example in the code block is not valid JSON (it shows only a property without surrounding braces). This can confuse readers and breaks JSON syntax highlighting/validation in many renderers. Consider showing a minimal valid JSON object instead.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"

[Copilot]

Pull request overview

Copilot reviewed 71 out of 71 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

api_app/models/schemas/shared_service_template.py:51

• The sample schema example has a grammatical error ("These is") and the $id path uses myshared_service, which is inconsistent with the test fixture (mysharedservice) and other examples. Align the $id and fix the wording to avoid confusing API consumers.

                    "$schema": "https://json-schema.org/draft/2020-12/schema",
                    "$id": "https://github.com/microsoft/AzureTRE/templates/shared_services/myshared_service/shared_service.json",
                    "type": "object",
                    "title": "My Shared Service Template",
                    "description": "These is a test shared service resource template schema",

api_app/models/schemas/workspace_service_template.py:52

• The sample schema example contains a grammatical error ("These is"). This text is surfaced in API schema examples, so it should read correctly.

                    "$schema": "https://json-schema.org/draft/2020-12/schema",
                    "$id": "https://github.com/microsoft/AzureTRE/templates/workspaces/myworkspace/workspace_service.json",
                    "type": "object",
                    "title": "My Workspace Service Template",
                    "description": "These is a test workspace service resource template schema",

api_app/models/schemas/user_resource_template.py:51

• The sample schema example contains a grammatical error ("These is"). This is part of the API example payload and should read correctly.

                    "$schema": "https://json-schema.org/draft/2020-12/schema",
                    "$id": "https://github.com/microsoft/AzureTRE/templates/workspaces/myworkspace/user_resource.json",
                    "type": "object",
                    "title": "My User Resource Template",
                    "description": "These is a test user resource template schema",

api_app/tests_ma/conftest.py:129

• This test fixture schema has a grammatical error ("These is"). Fixing it improves readability and keeps fixtures aligned with the API schema examples.

            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "$id": "https://github.com/microsoft/AzureTRE/templates/workspaces/myworkspace/user_resource.json",
            "type": "object",
            "title": "My User Resource Template",
            "description": "These is a test user resource template schema",

[Copilot]

Pull request overview

Copilot reviewed 71 out of 71 changed files in this pull request and generated 2 comments.

[Copilot]

🟡 Not ready to approve

The updated documentation contains an inaccurate statement about $id fragments in Draft 2020-12 that should be reworded to reflect recommended practice rather than a prohibition.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Comments suppressed due to low confidence (1)

docs/tre-workspace-authors/authoring-workspace-templates.md:94

• The note claims that in JSON Schema Draft 2020-12, $id "cannot contain fragment identifiers" (e.g. #/properties/...). $id is an IRI reference used to identify schema resources and establish the base IRI for resolving relative $ref; fragments are not inherently invalid, but using $id with fragments on individual properties is unnecessary and can change reference resolution. Consider rewording this to describe the recommended practice rather than stating it's prohibited.

!!! note
    **`$id` is not required on individual properties or subschemas.** Properties defined under "properties" are natively addressable by standard JSON Pointer (e.g. `#/properties/property_name`).
    * In JSON Schema Draft 2020-12, `$id` is strictly reserved for declaring base URIs (e.g. at the root schema level) and cannot contain fragment identifiers (such as `#/properties/...`). If custom plain-name anchors are needed within a subschema, use `$anchor` instead.

• Files reviewed: 70/70 changed files
• Comments generated: 0 new
• Review effort level: Low

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟢 Ready to approve

The changes are consistent, low-risk metadata/docs/test updates with version bumps, and only minor nits were identified.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Comments suppressed due to low confidence (2)

docs/tre-workspace-authors/authoring-workspace-templates.md:78

• Use consistent capitalization for the JSON Schema standard name (elsewhere in this doc it’s written as “JSON Schema”).

This file follows the [JSON schema standard](https://json-schema.org/) Draft 2020-12 (`https://json-schema.org/draft/2020-12/schema`) and can be used by a user interface to generate a UI for the user to input the parameters.

templates/workspace_services/openai/template_schema.json:3

• The PR description lists the files updated to Draft 2020-12, but this template schema was also updated and isn’t included in that list; please update the PR description so the scope is accurately documented for reviewers and release notes.

• Files reviewed: 71/71 changed files
• Comments generated: 0 new
• Review effort level: Low

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Not ready to approve

The updated docs JSON schemas include internal inconsistencies (e.g., required fields not matching defined property names) that should be corrected before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Comments suppressed due to low confidence (3)

docs/schemas/resource-assignment.json:3

• In this schema, the required list includes resourceId, but the properties section defines ResourceId (capital R). This makes the schema inconsistent (it will never require the intended property). Rename the property key to resourceId (or update the required list) so they match.

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",

docs/schemas/resource.json:3

• This schema requires resourceVersion, but the corresponding property is currently named ResourceVersion (capital R). That mismatch makes the schema’s required constraint ineffective. Rename the property key to resourceVersion (or update required) so they match.

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",

docs/schemas/operation.json:3

• In the $defs.event schema, the required list includes message, but the properties define description (whose description text says “Event message.”). This makes the subschema internally inconsistent and can break consumers relying on the schema. Please align the property name and the required entry (e.g., rename description to message, or require description instead).

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",

• Files reviewed: 71/71 changed files
• Comments generated: 0 new
• Review effort level: Low

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟢 Ready to approve

The changes consistently update schema declarations to Draft 2020-12 across code, templates, docs, and tests, and the repo’s pinned jsonschema dependency supports Draft 2020-12 validation.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

• Files reviewed: 71/71 changed files
• Comments generated: 0 new
• Review effort level: Low

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Marcus Robinson (marrobi)]

James Chapman (@JC-wk) think this needs extended tets?

[James Chapman (JC-wk)]

James Chapman (@JC-wk) think this needs extended tets?

They already passed https://github.com/microsoft/AzureTRE/actions/runs/30441451183

[Copilot]

🟡 Not ready to approve

The updated docs schema for resourceVersion still documents the field as a string, which conflicts with the API’s integer resourceVersion and should be corrected to avoid misleading consumers.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Suppressed comments (1)

docs/schemas/resource.json:22

• resourceVersion is documented as a string here, but the TRE API models expose resourceVersion as an integer (e.g., api_app/models/domain/resource.py). This schema should use an integer type to avoid misleading consumers of the docs.

        "resourceVersion": {
            "type": "string",
            "description": "Resource version."
        },

• Files reviewed: 71/71 changed files
• Comments generated: 0 new
• Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Human review recommended

The change updates schema drafts across many templates and validation touchpoints, and warrants a final human review to confirm end-to-end compatibility in real deployments.

Review details

• Files reviewed: 73/73 changed files
• Comments generated: 0 new
• Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

Pull request overview

Copilot reviewed 71 out of 71 changed files in this pull request and generated no new comments.