.. _feature_validation:

Validation - $validate
======================

.. note::

  The features described on this page are available in **all** :ref:`Firely Server editions <vonk_overview>`.

Firely Server can validate a resource against a profile as defined in the `$validate`_ operation. 

You can call validate on three levels:

#. :ref:`feature_validation_system`
#. :ref:`feature_validation_type`
#. :ref:`feature_validation_instance`

Besides that you can configure Firely Server to validate every incoming resource and even filter on specific profiles. See the section on :ref:`feature_prevalidation`.
In all cases, the :ref:`feature_validation_pre` is that Firely Server must have access to all relevant StructureDefinitions.

Validation has some :ref:`feature_validation_limitations`.

.. note::

    The very first validation call will take a considerable amount of time, typically around 5 seconds. This is because Firely Server maintains a cache of validation information, and on the first call that cache is still empty.
    Subsequent calls are much faster.

.. _feature_validation_system:

Validate on the system level
----------------------------
::

    POST <firely_server_endpoint>/$validate[?profile=<canonical-url-of-structuredefinition>]

There are two ways of calling $validate:

#. With a Resource or a Bundle of resources as body, and optionally, a profile parameter on the url.
#. With a Parameters resource as body, having

    * a parameter element with the Resource to validate in the resource parameter;
    * (optionally) the profile to validate against in the profile parameter

In both cases the request must have a Content-Type header matching the format of the body (``application/fhir+json`` or ``application/fhir+xml``).

If you do not specify a profile parameter, Firely Server will validate the Resource against any profiles mentioned in ``meta.profile`` as well as the base profile from the FHIR Specification.

If you call $validate on the system level, Firely Server will make no assumptions about the ResourceType of the Resource to validate.

.. _feature_validation_type:

Validate on the ResourceType level
----------------------------------
::

    POST <firely_server_endpoint>/<resourcetype>/$validate[?profile=<canonical-url-of-structuredefinition>]

You can call $validate in the same two ways as with :ref:`feature_validation_system`.

If you call $validate on the ResourceType level, Firely Server will check whether the Resource to validate is of the same <resourcetype> as provided in the url.

.. _feature_validation_instance:

Validate an instance from the database
--------------------------------------
::

    GET <firely_server_endpoint>/<resourcetype>/<id>/$validate[?profile=<canonical-url-of-structuredefinition>]

This time you can only use the (optional) profile parameter on the url to specify a StructureDefinition to validate against.

.. _feature_validation_pre:

Precondition
------------

Firely Server must be aware of all the StructureDefinitions referenced directly via parameter or indirectly by a profile in ``meta.profile``. Refer to the :ref:`conformance` for more information.

.. _feature_validation_limitations:

Limitations
-----------

#. The mode parameter is not yet supported.
#. Implicit ValueSets (ones that use the .filter property) are not supported - create explicit ones instead (without the .filter property).

.. _`$validate`: http://www.hl7.org/implement/standards/fhir/resource-operations.html#validate