.. _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 structure is:

============================ ==================================================================================================================================================================================================================================================
Field name                   Description
============================ ==================================================================================================================================================================================================================================================
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 structure is:

====================== ===============================================================================================================================================================================================================================================================================================
Field name             Description
====================== ===============================================================================================================================================================================================================================================================================================
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 structure is:

=================== =======================================================================================================================================================================================
Field name          Description
=================== =======================================================================================================================================================================================
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 structure is:

========== ===========================
Field name Description
========== ===========================
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>`
