.. _gmlas_metadata_layers:

GMLAS - Metadata layers
=======================

This page details the structure of the extra metadata layers reported by
the :ref:`vector.gmlas` driver.

\_ogr_fields_metadata layer
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This layer gives metadata about OGR fields, and also "abstract" fields
that describe the relation ship between a parent and child layer.

Its fields are:

- ``layer_name``: Name of the layer to which the field belongs to

- ``field_name``: Name of the field. May be null when field_category is
  PATH_TO_CHILD_ELEMENT_NO_LINK or GROUP

- ``field_xpath``: XPath of the element/attribute whose content is used for
  the field. The XPath is relative to the element that is the direct parent
  of this element/attribute, or a parent element in case of flattening. May be
  null for a field generated by OGR.

- ``field_type``: the XML schema base data type (string, int, long, ID, ...).
  Extended with "geometry". May be null for a field generated by OGR

- ``field_is_list``: Whether the XML type is a list.

- ``field_min_occurs``: Integer value with the minimum number of occurrences of
  values. 0 or 1 typically. Or more for array types. May be null for a field
  generated by OGR

- ``field_max_occurs``: Integer value with the maximum number of occurrences of
  values. 1 typically. Or more for array types. 2147483647 means unlimited.
  May be null for a field generated by OGR

- ``field_repetition_on_sequence``: Boolean value to indicate if the field is
  related to a <sequence maxOccurs=">1 or unbounded"> construct. Only set when
  field_max_occurs is not 0 or 1.

- ``field_default_value``: Default value of the field, or null

- ``field_fixed_value``: Fixed value of the field, or null

- ``field_category``: Category of the field. May be REGULAR,
  PATH_TO_CHILD_ELEMENT_NO_LINK, PATH_TO_CHILD_ELEMENT_WITH_LINK,
  PATH_TO_CHILD_ELEMENT_WITH_JUNCTION_TABLE, GROUP or SWE_FIELD.
  May be null for a field generated by OGR.

- ``field_related_layer``: Name of the child layer for field_category != REGULAR

- ``field_junction_layer``: Name of the junction layer. Only set if
  field_category is equal to PATH_TO_CHILD_ELEMENT_WITH_JUNCTION_TABLE

- ``field_documentation``: Documentation from the schema.

Explanation of field_category values:

-  REGULAR: the field is made from the value of an element or attribute
   that is a direct child of the element that is the root of the layer
   considered.
-  PATH_TO_CHILD_ELEMENT_NO_LINK: A field declared with this category is
   not instantiated as a OGR field of the layer 'layer_name'. It is
   merely there to declare the relationship between the parent and child
   layers. This is when a sub-element is of a complex type or a repeated
   sub-element of simple type that does not match one of the OGR array
   types.
-  PATH_TO_CHILD_ELEMENT_WITH_LINK: the content of this field is the
   primary key of a OGR feature of another layer. The
   field_related_layer field contains the name of that linked layer.
-  PATH_TO_CHILD_ELEMENT_WITH_JUNCTION_TABLE: A field declared with this
   category is not instantiated as a OGR field of the layer
   'layer_name'. It is merely there to declare the relationship between
   the parent and child layers. This is when the link between the parent
   and child layer is done through a junction table (case where the
   child layer is referenced by other parent layers).
-  GROUP: A field declared with this category is not instantiated as a
   OGR field of the layer 'layer_name'. It is merely there to declare
   the relationship between the parent and child layers. This is when a
   layer uses XML schema group constructs with repeated cardinality.
-  SWE_FIELD: A field derived from special processing of swe:DataRecord
   or swe:DataArray elements.


\_ogr_layers_metadata layer
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This layer gives metadata about OGR layers.

Its fields are:

- ``layer_name``: Name of the layer

- ``layer_xpath``: XPath of the element that is used as the root element for
  the layer. May be suffixed with ";extra=XXXX" for group constructs or repeated
  sequences of repeated elements, so as to distinguish for the XPath of their
  parent element. Will be null for junction tables or SWE_DATA_ARRAY layers.

- ``layer_category``: Category of the layer. One of TOP_LEVEL_ELEMENT,
  NESTED_ELEMENT, JUNCTION_TABLE or SWE_DATA_ARRAY

- ``layer_pkid_name``: Name of the primary key field. This is the text attribute
  that uniquely identified a feature (in its layer). This is the XML
  attribute/name of type xs:ID when it exists, otherwise a "ogr_pkid" field is
  automatically created. Will be null for SWE_DATA_ARRAY layers.

- ``layer_parent_pkid_name``: Name of the field that is a foreign key to the
  parent layer of this layer. Only set for a NESTED_ELEMENT layer.

- ``layer_documentation``: Documentation from the schema.


\_ogr_layer_relationships layer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This layer gives metadata about relationship between OGR layers.

Its fields are:

- ``parent_layer``: Name of the parent layer

- ``parent_pkid``: Name of the primary key of the parent layer

- ``parent_element_name``: Name of the XML element that links from the parent
  to the child. Will be null when the child layer is due to group constructs or
  repeated sequences of repeated elements of the parent.

- ``child_layer``: Name of the child layer

- ``child_pkid``: Name of the primary key of the child layer. Will be null for
  SWE_DATA_ARRAY layers


\_ogr_other_metadata layer
~~~~~~~~~~~~~~~~~~~~~~~~~~

This layer contains key / value pairs with different information.

Its fields are:

- ``key``: Name of the metadata item
- ``value``: Value of the metadata imtem

Possible keys are :

-  document_filename: Filename of the XML/GML file read.
-  configuration_filename: Filename of the XML configuration file used.
-  configuration_inlined: XML content of the configuration file.
-  namespace_uri_XX: URI of a namespace referenced by the schema(s).
-  namespace_location_XX: Location of a schema.
-  namespace_prefix_XX: Prefix of a namespace referenced by the
   schema(s).
-  gml_version: GML version, such as 2.1.2, 3.1.1 or 3.2.1

See Also
--------

-  :ref:`main documentation page for GMLAS driver <vector.gmlas>`
