{
  "openapi": "3.0.2",
  "info": {
    "title": "PSGC Terminology Server Capability Statement",
    "description": "Defines what a conformant PSGC-capable FHIR terminology server SHALL and SHOULD support.",
    "license": {
      "name": "Apache License 2.0",
      "url": "http://spdx.org/licenses/Apache-2.0.html"
    },
    "version": "0.1.0",
    "contact": {
      "name": "CSIRO Australian e-Health Research Centre",
      "url": "https://aehrc.csiro.au"
    }
  },
  "externalDocs": {
    "url": "https://australian-e-health-research-centre.gitlab.io/psgc-fhir-ig/CapabilityStatement/psgc-terminology-server",
    "description": "FHIR CapabilityStatement"
  },
  "paths": {
    "/metadata": {
      "summary": "Access to the Server\u0027s Capability Statement",
      "description": "All FHIR Servers return a CapabilityStatement that describes what services they perform",
      "get": {
        "summary": "Return the server\u0027s capability statement",
        "operationId": "metadata",
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "the capbility statement",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/CapabilityStatement"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/CapabilityStatement.xsd"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/format"
          },
          {
            "$ref": "#/components/parameters/pretty"
          },
          {
            "$ref": "#/components/parameters/summary"
          },
          {
            "$ref": "#/components/parameters/elements"
          }
        ]
      }
    },
    "/CodeSystem/$validate-code": {
      "summary": "Operation $validate-code on type CodeSystem",
      "description": "Operation $validate-code on type CodeSystem",
      "get": {
        "summary": "$validate-code on type CodeSystem",
        "description": "Validate that a coded value is in the code system. If the operation is not called at the instance level, one of the parameters \"url\" or \"codeSystem\" must be provided. The operation returns a result (true / false), an error message, and the recommended display for the code.\n\nWhen invoking this operation, a client SHALL provide one (and only one) of the parameters (code+system, coding, or codeableConcept). Other parameters (including version and display) are optional",
        "operationId": "op-validate-code-CodeSystem",
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    },
    "/CodeSystem/{rid}/$validate-code": {
      "summary": "Operation $validate-code on instance of CodeSystem",
      "description": "Operation $validate-code on an instance of CodeSystem",
      "get": {
        "summary": "$validate-code on CodeSystem instance",
        "description": "Validate that a coded value is in the code system. If the operation is not called at the instance level, one of the parameters \"url\" or \"codeSystem\" must be provided. The operation returns a result (true / false), an error message, and the recommended display for the code.\n\nWhen invoking this operation, a client SHALL provide one (and only one) of the parameters (code+system, coding, or codeableConcept). Other parameters (including version and display) are optional",
        "operationId": "op-validate-code-CodeSystem-instance",
        "parameters": [
          {
            "$ref": "#/components/parameters/rid"
          }
        ],
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    },
    "/CodeSystem/$lookup": {
      "summary": "Operation $lookup on type CodeSystem",
      "description": "Operation $lookup on type CodeSystem",
      "get": {
        "summary": "$lookup on type CodeSystem",
        "description": "Given a code/system, or a Coding, get additional details about the concept, including definition, status, designations, and properties. One of the products of this operation is a full decomposition of a code from a structured terminology.\n\nWhen invoking this operation, a client SHALL provide both a system and a code, either using the system+code parameters, or in the coding parameter. Other parameters are optional",
        "operationId": "op-lookup-CodeSystem",
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    },
    "/CodeSystem/$subsumes": {
      "summary": "Operation $subsumes on type CodeSystem",
      "description": "Operation $subsumes on type CodeSystem",
      "get": {
        "summary": "$subsumes on type CodeSystem",
        "description": "Test the subsumption relationship between code/Coding A and code/Coding B given the semantics of subsumption in the underlying code system (see [hierarchyMeaning](codesystem-definitions.html#CodeSystem.hierarchyMeaning)).\n\nWhen invoking this operation, a client SHALL provide both a and codes, either as code or Coding parameters. The system parameter is required unless the operation is invoked on an instance of a code system resource. Other parameters are optional",
        "operationId": "op-subsumes-CodeSystem",
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    },
    "/CodeSystem/{rid}/$subsumes": {
      "summary": "Operation $subsumes on instance of CodeSystem",
      "description": "Operation $subsumes on an instance of CodeSystem",
      "get": {
        "summary": "$subsumes on CodeSystem instance",
        "description": "Test the subsumption relationship between code/Coding A and code/Coding B given the semantics of subsumption in the underlying code system (see [hierarchyMeaning](codesystem-definitions.html#CodeSystem.hierarchyMeaning)).\n\nWhen invoking this operation, a client SHALL provide both a and codes, either as code or Coding parameters. The system parameter is required unless the operation is invoked on an instance of a code system resource. Other parameters are optional",
        "operationId": "op-subsumes-CodeSystem-instance",
        "parameters": [
          {
            "$ref": "#/components/parameters/rid"
          }
        ],
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    },
    "/CodeSystem/$expand-psgc": {
      "summary": "Operation $expand-psgc on type CodeSystem",
      "description": "Operation $expand-psgc on type CodeSystem",
      "get": {
        "summary": "$expand-psgc on type CodeSystem",
        "description": "Search PSGC area names using full-text matching. Returns a ValueSet expansion.",
        "operationId": "op-expand-psgc-CodeSystem",
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    },
    "/CodeSystem/$geo-lookup": {
      "summary": "Operation $geo-lookup on type CodeSystem",
      "description": "Operation $geo-lookup on type CodeSystem",
      "get": {
        "summary": "$geo-lookup on type CodeSystem",
        "description": "Find PSGC codes by parent code prefix and/or geographic level. Exploits the positional encoding of the 10-digit PSGC code.",
        "operationId": "op-geo-lookup-CodeSystem",
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    },
    "/CodeSystem/$geo-hierarchy": {
      "summary": "Operation $geo-hierarchy on type CodeSystem",
      "description": "Operation $geo-hierarchy on type CodeSystem",
      "get": {
        "summary": "$geo-hierarchy on type CodeSystem",
        "description": "Resolve the full geographic ancestry path for a PSGC code — from region down to the code\u0027s own level.",
        "operationId": "op-geo-hierarchy-CodeSystem",
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    },
    "/ConceptMap/$translate": {
      "summary": "Operation $translate on type ConceptMap",
      "description": "Operation $translate on type ConceptMap",
      "get": {
        "summary": "$translate on type ConceptMap",
        "description": "Translate a code from one value set to another, based on the existing value set and concept maps resources, and/or other additional knowledge available to the server. \r\n\r\n One (and only one) of the in parameters (code, coding, codeableConcept) must be provided, to identify the code that is to be translated.  \r\n\r\n The operation returns a set of parameters including a \u0027result\u0027 for whether there is an acceptable match, and a list of possible matches. Note that the list of matches may include notes of codes for which mapping is specifically excluded, so implementers have to check the match.equivalence for each match",
        "operationId": "op-translate-ConceptMap",
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    },
    "/ConceptMap/{rid}/$translate": {
      "summary": "Operation $translate on instance of ConceptMap",
      "description": "Operation $translate on an instance of ConceptMap",
      "get": {
        "summary": "$translate on ConceptMap instance",
        "description": "Translate a code from one value set to another, based on the existing value set and concept maps resources, and/or other additional knowledge available to the server. \r\n\r\n One (and only one) of the in parameters (code, coding, codeableConcept) must be provided, to identify the code that is to be translated.  \r\n\r\n The operation returns a set of parameters including a \u0027result\u0027 for whether there is an acceptable match, and a list of possible matches. Note that the list of matches may include notes of codes for which mapping is specifically excluded, so implementers have to check the match.equivalence for each match",
        "operationId": "op-translate-ConceptMap-instance",
        "parameters": [
          {
            "$ref": "#/components/parameters/rid"
          }
        ],
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    },
    "/Location/$resolve-psgc": {
      "summary": "Operation $resolve-psgc on type Location",
      "description": "Operation $resolve-psgc on type Location",
      "get": {
        "summary": "$resolve-psgc on type Location",
        "description": "Reverse geocoding: resolve latitude/longitude to the PSGC code hierarchy via point-in-polygon spatial query.",
        "operationId": "op-resolve-psgc-Location",
        "responses": {
          "default": {
            "description": "Error, with details",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/OperationOutcome"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/OperationOutcome.xsd"
                }
              }
            }
          },
          "200": {
            "description": "Operation response",
            "content": {
              "application/fhir+json": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/fhir.schema.json#/definitions/Parameters"
                }
              },
              "application/fhir+xml": {
                "schema": {
                  "$ref": "https://hl7.org/fhir/R4/Parameters.xsd"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "rid": {
        "name": "rid",
        "in": "path",
        "description": "id of the resource (\u003dResource.id)",
        "required": true,
        "allowEmptyValue": false,
        "style": "simple",
        "schema": {
          "type": "string"
        }
      },
      "hid": {
        "name": "hid",
        "in": "path",
        "description": "id of the history entry (\u003dResource.meta.versionId)",
        "required": true,
        "allowEmptyValue": false,
        "style": "simple",
        "schema": {
          "type": "string"
        }
      },
      "summary": {
        "name": "_summary",
        "in": "query",
        "description": "Requests the server to return a designated subset of the resource",
        "allowEmptyValue": true,
        "style": "form",
        "schema": {
          "type": "string",
          "enum": [
            "true",
            "text",
            "data",
            "count",
            "false"
          ]
        }
      },
      "format": {
        "name": "_format",
        "in": "query",
        "description": "Specify alternative response formats by their MIME-types (when a client is unable acccess accept: header)",
        "allowEmptyValue": true,
        "style": "form",
        "schema": {
          "type": "string",
          "format": "mime-type"
        }
      },
      "pretty": {
        "name": "_pretty",
        "in": "query",
        "description": "Ask for a pretty printed response for human convenience",
        "allowEmptyValue": true,
        "style": "form",
        "schema": {
          "type": "boolean"
        }
      },
      "elements": {
        "name": "_elements",
        "in": "query",
        "description": "Requests the server to return a collection of elements from the resource",
        "allowEmptyValue": true,
        "style": "form",
        "explode": false,
        "schema": {
          "type": "array",
          "format": "string",
          "items": {
            "format": "string"
          }
        }
      },
      "count": {
        "name": "_count",
        "in": "query",
        "description": "The maximum number of search results on a page. The server is not bound to return the number requested, but cannot return more",
        "schema": {
          "type": "number"
        }
      }
    }
  }
}