.. _schema_services: Schema Services =============== Metadata schemas can be plugged into GeoNetwork - see :ref:`schemaPlugins`. Any application that needs to: - find information (eg. names, versions, namespaces, converters) about metadata schemas that are plugged into GeoNetwork should use the :ref:`xml.info` service - find information about the schema elements and codelists should use the ``xml.schema.info`` service described in this section of the manual - add, delete, update schema plugins in GeoNetwork should use the ``xml.metadata.schema.add``, ``xml.metadata.schema.delete`` and ``xml.metadata.schema.update`` services described in this section of the manual Metadata Schema Information (xml.info?type=schemas) --------------------------------------------------- See :ref:`xml.info` for more details. .. index:: xml.schema.info Schema Element and Codelist Information (xml.schema.info) --------------------------------------------------------- This service returns information about a set of schema elements or codelists. The returned information consists of a localised label, a description, conditions that the element must satisfy etc. Request ``````` Requests to this service can only be made using the HTTP POST binding with application/XML content type. Requests can ask for information on multiple elements and codelists from different schemas. Description of the request fields is as follows: - **element**: Must contain a **schema** and a **name** attribute. The schema attribute must be the name of a schema currently registered in GeoNetwork (see :ref:`xml.info` for more details). The name attribute must be the qualified name of the metadata schema element on which information is required. Other optional attributes can be specified to help determine the appropriate context for the metadata element. These optional attributes are: - **context**: The qualified name of the metadata schema element that is the parent of the element specified in the **name** attribute. - **fullContext**: The qualified xpath of the element specified in the **name** attribute. - **isoType**: For profiles of ISO19115/19139 only. The qualified name of the element in the base ISO19115/19139 schema that the element specified in the **name** attribute is a substitute for. eg. in the Marine Community Profile of ISO19115/19139, ``mcp:MD_Metadata`` is a substitute for ``gmd:MD_Metadata`` in the base ISO19115/19139 metadata schema. - **codelist**: Accepts a **schema** and **name** attribute as for **element** but information on any codelist associated with the qualified name of the metadata schema element in the **name** attribute will be returned instead. :: .. note:: The text returned is localised into the language specified in the the service call. eg. A call to /geonetwork/srv/eng/xml.schema.info will return text in the English (eng) language. Response ```````` If the request executed successfully then HTTP status code 200 will be returned along with an XML document containing the response. The root field of the response will be populated with information about the element/codelist specified in the request. The fields of the response are: - **element**: A container for information about a schema element. It has a name attribute which contains the qualified name of the element. - **label**: The human readable name of the element, localised into the language specified in the request. - **description**: A generic description of the element. - **condition \[0..1]**: This field is optional and indicates if the element must satisfy a condition eg. mandatory. The condition text is displayed with the element name so it intended to be human readable. - **codelist**: A container for information about a codelist. It has a name attribute which contains the qualified name of the codelist. - **entry \[1..n]**: A container for a codelist entry. There can be more than one entry. - **code**: The entry code. This is the value that will be used in the metadata. - **label**: This is a human readable name for the code, used to show the code in the user interface. It is localised. - **description**: A localised description/meaning of the code. The description is shown in the user interface with the label. :: language used in Application Schema mandatory creation date when the resource was brought into existence publication date when the resource was issued revision date identifies when the resource was examined or re-examined and improved or amended Error management ```````````````` If an exception occurs during the processing of the request, then an HTTP 500 status code is returned along with an XML document describing the exception. See :ref:`exception_handling` for more details. Apart from exceptions, the service can encounter errors trying to retrieve an element/codelist information eg. if the requested element is not present. If such an error is encountered, then the object is copied from the response and an error attribute is added describing the error. An example of such a response is:: .. _table_schema_errors: Possible errors returned by xml.schema.info service: ================= ============================================================ Error code Description ================= ============================================================ unknown-schema The specified schema is not supported unknown-namespace The namespace of the specified prefix was not found not-found The requested element / codelist was not found ================= ============================================================ .. index:: xml.metadata.schema.add Add a metadata schema (xml.metadata.schema.add) ----------------------------------------------- The **xml.metadata.schema.add** service can be used to add a metadata schema to GeoNetwork. The details of what the schema should contain are covered in the :ref:`schemaPlugins` section of this manual. Only **Administrator** users can run this service. Requires authentification: Yes Request ``````` Parameters: - **schema**: (mandatory) Name of the schema to add. *One* of the following parameters: - **fname**: Server file name (full path) to metadata schema zip archive. - **url**: Http URL of metadata schema zip archive. - **uuid**: Uuid of metadata record in current catalog that has a metadata schema zip archive uploaded and stored with it. Schema add request example:: Url: http://localhost:8080/geonetwork/srv/eng/xml.metadata.schema.add Mime-type: application/xml Post request: iso19139.mcp /usr/local/src/git/schemaPlugins-2.8.x/dist/iso19139.mcp.zip Response ```````` If the request executed succesfully then an HTTP 200 status code is returned and an XML document confirming success is returned. An example response is::: If the request fails then an HTTP 500 status code error is returned and the response contains an XML document with the details of the exception/what went wrong. An example error response is::: Schema already exists OperationAbortedEx ..... See :ref:`exception_handling` for more details. .. index:: xml.metadata.schema.update Update a metadata schema (xml.metadata.schema.update) ----------------------------------------------------- The **xml.metadata.schema.update** service can be used to update a metadata schema in GeoNetwork. The details of what the schema should contain are covered in the :ref:`schemaPlugins` section of this manual. Only **Administrator** users can run this service. Requires authentification: Yes Request ``````` Parameters: - **schema**: (mandatory) Name of the schema to update. Must be the name of a currently registered metadata schema in GeoNetwork. *One* of the following parameters: - **fname**: Server file name (full path) to metadata schema zip archive. - **url**: Http URL of metadata schema zip archive. - **uuid**: Uuid of metadata record in current catalog that has a metadata schema zip archive uploaded and stored with it. Schema update request example:: Url: http://localhost:8080/geonetwork/srv/eng/xml.metadata.schema.update Mime-type: application/xml Post request: iso19139.mcp /usr/local/src/git/schemaPlugins-2.8.x/dist/iso19139.mcp.zip Response ```````` If the request executed succesfully then an HTTP 200 status code is returned and an XML document confirming success is returned. An example response is::: If the request fails then an HTTP 500 status code error is returned and the response contains an XML document with the details of the exception/what went wrong. An example error response is::: Schema doesn't exist OperationAbortedEx ..... See :ref:`exception_handling` for more details. .. index:: xml.metadata.schema.delete Delete a metadata schema (xml.metadata.schema.delete) ----------------------------------------------------- The **xml.metadata.schema.delete** service can be used to delete a metadata schema in GeoNetwork. A metadata schema can only be deleted if: - there are no metadata records in the catalog that use it - no other metadata schema is dependent on it Only **Administrator** users can run this service. Requires authentification: Yes Request ``````` Parameters: - **schema**: (mandatory) Name of the schema to delete. Must be the name of a currently registered metadata schema in GeoNetwork. Schema delete request example:: Url: http://localhost:8080/geonetwork/srv/eng/xml.metadata.schema.delete Mime-type: application/xml Post request: iso19139.mcp Response ```````` If the request executed without an exception then an HTTP 200 status code is returned and an XML document giving status is returned. An example response is::: Other responses may describe errors, in which case the status is set to "error". An example error response is::: If the request fails due to an exception in the service then an HTTP 500 status code error is returned and the response contains an XML document with the details of the exception/what went wrong. An example error response is::: Schema doesn't exist OperationAbortedEx ..... See :ref:`exception_handling` for more details.