####################
Survey Metadata File
####################

Global attributes for the Survey group are passed through the dataset attributes, ``dataset_attrs`` dictionary. The fields below are mostly all **required** attributes (see :doc:`this page for requirements <index>`). Additional fields are welcome at the user's discretion. See `CF conventions <https://cfconventions.org/Data/cf-conventions/cf-conventions-1.13/cf-conventions.html#description-of-file-contents>`_ for full description of these fields.

The fields ``gspy_version`` and ``conventions`` are automatically generated by GSPy following the current package version in use. 

When importing from a YAML file, the ``content`` field of the survey group should only contain a statement of that individual group's content. Then, when exporting a survey DataTree, GSPy combs through the ``content`` of all subtree groups beneath the survey and appends them such that the final ``content`` as written to file for the survey group reflects the entire contents of the tree. See examples for demonstrations.

.. literalinclude:: ../../_static/template_survey_md.yml
   :language: yaml
   :linenos:
   :lineno-match:
   :lines: 1-12

Coordinate reference system (CRS) information is passed through the ``spatial_ref`` dictionary. GSPy requires at least one of the following fields to generates the complete spatial_ref coordinate variable with all necessary fields to accurately plot in GIS software. 

.. literalinclude:: ../../_static/template_survey_md.yml
   :language: yaml
   :linenos:
   :lineno-match:
   :lines: 12-20

Additional global metadata that pertains to the Survey and all the datasets it will contain can be added as discrete dictionaries. These metadata fields are entirely up to the user's discretion. The sections shown here are not required, but are shown to demonstrate the type of information intended and how it should be formatted:

.. literalinclude:: ../../_static/template_survey_md.yml
   :language: yaml
   :linenos:
   :lineno-match:
   :lines: 20-44