--- a/Sphinx/source/faq/features.rst	Wed Dec 14 11:04:32 2016 +0100
+++ b/Sphinx/source/faq/features.rst	Wed Dec 14 11:51:11 2016 +0100
@@ -73,3 +73,110 @@
 
 Compression is controlled by the ``StorageCompression`` option in the
 :ref:`Orthanc configuration file <configuration>`.
+
+
+.. _metadata:
+
+Metadata
+--------
+
+Metadata consists in an **associative key-value array** (mapping a
+integer key in the range [0,65535] to a string value) that is
+associated with each :ref:`DICOM resource <orthanc-ids>` stored inside
+Orthanc (may it be a patient, a study, a series or a DICOM
+instance). Metadata can be either referred to using the integer key,
+or using a symbolic name (if configured).  Metadata records
+information that is not readily available in the DICOM tags.
+
+In spirit, the metadata mechanism is similar to the :ref:`attachment
+mechanism <orthanc-storage>`. However, metadata is stored directly
+inside the database, whereas attachments are stored as separate files
+on the filesystem (the database only stores a reference to the
+attachments). Choosing between metadata and attachments is a matter of
+trade-off: Metadata must be kept small (as a rule of thumb, under 1KB)
+and used if fast access is needed, whereas attachments can be used to
+store arbitrarily large piece of data.
+
+
+Core metadata
+^^^^^^^^^^^^^
+
+Here are the main metadata handled by the Orthanc core:
+
+* ``ReceptionDate`` records when a DICOM instance was received by
+  Orthanc. Similarly, ``LastUpdate`` records, for each
+  patient/study/series, the last time a DICOM instance was added to
+  this resource.
+* ``RemoteAet`` records the AET of the modality that has sent some
+  DICOM instance to Orthanc.
+* ``ModifiedFrom`` and ``AnonymizedFrom`` hold from which original
+  resource, a resource was modified or anonymized. The presence of
+  this metadata indicates that the resource is the result of a
+  modification or anonymization that was carried on by Orthanc.
+* ``Origin`` records through which mechanism the instance was received
+  by Orthanc (may be ``Unknown``, ``DicomProtocol``, ``RestApi``,
+  ``Plugins``, or ``Lua``).
+* ``IndexInSeries`` records the expected index of a DICOM instance
+  inside its parent series. Conversely, ``ExpectedNumberOfInstances``
+  associates to each series, the number of DICOM instances this series
+  is expected to contain.
+* Starting with Orthanc 1.2.0, ``TransferSyntax`` and ``SopClassUid``
+  respectively stores the transfer syntax UID and the SOP class UID of
+  DICOM instances, in order to speed up the access to this
+  information.
+
+Metadata listed above are set privately by the Orthanc core. They are
+**read-only** from the perspective of the end user, as Orthanc
+internally relies on them.
+
+
+User-defined metadata
+^^^^^^^^^^^^^^^^^^^^^
+
+The metadata described above where handled by the core of Orthanc.
+Orthanc users are however allowed to define their own **user-defined
+metadata**. Such metadata are associated with an integer key that is
+greater or equal to 1024 (whereas keys below 1023 are reserved for
+core metadata).
+
+You can associate a symbolic name to user-defined metadata using the
+``UserMetadata`` option inside the :ref:`configuration of Orthanc
+<configuration>`.
+
+
+Accessing metadata
+^^^^^^^^^^^^^^^^^^
+
+.. highlight:: bash
+
+Metadata associated with one DICOM resource can be accessed through
+the REST API, for instance::
+
+  $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata
+  $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/RemoteAet
+
+User-defined metadata can be modified by issuing a HTTP PUT against
+the REST API::
+
+  $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024 -X PUT -d 'hello'
+  $ curl http://localhost:8042/instances/cb855110-5f4da420-ec9dc9cb-2af6a9bb-dcbd180e/metadata/1024
+  hello
+
+
+
+.. _registry:
+
+Central registry of metadata and attachments
+--------------------------------------------
+
+Obviously, one must pay attention to the fact that different
+applications might use the same key to store different user-defined
+:ref:`metadata <metadata>`, which might result in incompatibilities
+between such applications. Similarly, incompatibilities might show up
+for user-defined :ref:`attachments <orthanc-storage>`.
+
+Developers of applications/plugins that use user-defined metadata or
+attachments are therefore kindly invited to complete the **central
+registry** below:
+
+* ``Metadata 4200`` is used by the plugin for :ref:`whole-slide imaging <wsi>`.

--- a/Sphinx/source/users/lua.rst	Wed Dec 14 11:04:32 2016 +0100
+++ b/Sphinx/source/users/lua.rst	Wed Dec 14 11:51:11 2016 +0100
@@ -86,7 +86,7 @@
   amount of time (cf. the option ``StableAge`` in the
   :ref:`configuration file <configuration>`). The :ref:`identifier
   <orthanc-ids>` of the patient is provided, together with her DICOM
-  tags and her metadata.
+  tags and her :ref:`metadata <metadata>`.
 * ``function OnStableSeries(seriesId, tags, metadata)``: Invoked
   whenever a series has not received any new instance for a certain
   amount of time.