## Utility Modules The following modules are used to highlight the information being documented in each of the above modules where prose may be needed to convey the critical metadata. The eml-text module provides a number of text-based constructs to enhance a document (including sections, paragraphs, lists, subscript, superscript, emphasis, etc.) ### The eml-text module - Text field formatting Links: - [Module Diagram](./images/eml-text.png) - [Interactive Module Documentation](./schema/eml-text_xsd.html) The eml-text module is a wrapper container that allows general text descriptions to be used within the various modules of eml. It can include either structured or unstructured text blocks. It isn\'t really appropriate to use this module outside of the context of a parent module, because the parent module determines the appropriate context to which this text description applies. The eml-text module allows one to provide structure to a text description in order to convey concepts such as sections (paragraphs), hierarchy (ordered and unordered lists), emphasis (bold, superscript, subscript) etc. The structured elements can be specified using a subset of [DocBook](http://www.docbook.org) so the predefined DocBook stylesheets can be used to style EML fields that implement this module, or alternatively can be specified using Markdown text blocks. Combinations of plain text, docbook sections, and markdown sections can be interleaved in any order, but most people will likely find the markdown syntax the easiest to use. ### The eml-semantics module - Semantic annotations for formalized statements about EML components Links: - [Module Diagram](./images/eml-semantics.png) - [Interactive Module Documentation](./schema/eml-semantics_xsd.html) The eml-semantics module defines types and elements for annotating other structures within EML with semantically-precise statements from various controlled vocabularies. This is accomplished by associating the global URI for a property and value with elements from EML, such as an attribute, an entity, or a dataset. It is used throughout the other EML modules where detailed semantic information is needed. For example, given an EML attribute named "tmpair", one might want to indicate semantically that the attribute is measuring the property "Temperature" from a sample of the entity "Air", where both of those terms are defined precisely in controlled vocabularies. The eml-semantics module defines an 'annotation' element and associated type that can be used within EML resources (dataset, software, etc.), EML Entities (dataTable, spatialRaster, spatialVector, otherEntity), and EML Attributes. They can also be applied within the EML additionalMetadata field to label arbitrary structures within EML, in which case the subject of the annotation is the element listed in the describes element within the additionalMetadata field. ### The eml-access module - Access control rules for resources **DEPRECATED** - *Note that use of the `eml-access` module is deprecated, as most systems have internal representations of access control and have not been provided or maintained. Thus, we no longer recommend using any of the `access` elements throughout the schema, even though they have been retained for backwards compatibility.* Links: - [Module Diagram](./images/eml-access.png) - [Interactive Module Documentation](./schema/eml-access_xsd.html) The eml-access module describes the level of access that is to be allowed or denied to a resource for a particular user or group of users, and can be described independently for metadata and data. The eml-access module uses a reference to a particular authentication system to determine the set of principals (users or groups) that can be specified in the access rules. The special principal \'public\' can be used to indicate that any user or group has access permission, thereby making it easier to specify that anonymous access is allowed. There are two mechanisms for including access control via the eml-access module: 1. The top-level \"eml\" element may have an optional \ element that is used to establish the default access control for the entire EML package. If this access element is omitted from the document, then the package submitter should be given full access to the package but all other users should be denied all access. To allow the package to be publicly viewable, the EML author must explicitly include a rule stating so. Barring the existence of a distribution-level \ element (see below), access to data entities will be controlled by the package-level \ element in the \ element. 2. Exceptions for particular entity-level components of the package can be controlled at a finer grain by using an access description in that entity\'s physical/distribution tree. When access control rules are specified at this level, they apply only to the data in the parent distribution element, and not to the metadata. Thus, it will control access to the content of the \ element, as well as resources that are referenced by the \ and \ paths. These exceptions to access for particular data resources are applied after the default access rules at the package-level have been applied, so they effectively override the default rules when they overlap. In previous versions of EML access rules for entity-level distribution were contained in \ sections and referenced via the \ tag. Although in theory these could have referenced any node, in application such node-level access control is problematic. Since the most common uses of access control rules were to limit access to specific data entities, the access tree has been placed there explicitly in EML 2.1.0. Access is specified with a choice of child elements, either \ or \. Within these rules, values can be assigned for each \ using the \ element. Users given \"read\" permission can view the resource; \"write\" allows changes to the resource excluding changes to the access rules; \"changePermission\" includes \"write\" plus the changing of access rules. Users allowed \"all\" permissions; may do all of the above. Access to data and metadata is affected by the order attribute of the \ element. It is possible for a deny rule to override an allow rule, and vice versa. In the case where the order attribute is set to \"allowFirst\", and there are rules similar to the following (with non-critical sections deleted): ```xml public read uid=alice,o=NASA,dc=ecoinformatics,dc=org read ``` the principal \"uid=alice \...\" will be denied access, because it is a member of the special \"public\" principal, and the deny rule is processed second. For this allow rule to truly allow access to that principal, the order attribute should be set to \"denyFirst\", and the allow rule will override the deny rule when it is processed second. An example is given below, with non-critical sections deleted: ```xml uid=alice,o=NASA,dc=ecoinformatics,dc=org read write ... ... ... ... ... uid=alice,o=NASA,dc=ecoinformatics,dc=org write ... ... ... access123 ... ``` In this example, the overall default access is to allow the user=alice (but no one else) to read and write all metadata and data. However, under \"entity123\" and \"entity234\", there is an additional rule saying that user=alice does not have write permission. The net effect is that Alice can read and make changes to the metadata, but cannot make changes to the two data entities. In addition, Alice cannot change these access rules; although the submitter can. This example also shows how the eml-access module, like other modules, may be \"referenced\" via the \ tag. This allows an access control document to be described once, and then used as a reference in other locations within the EML document via its ID. In summary, access rules can be applied in two places in an eml document. Default access rules are established in the top \ element for the main eml document (e.g., \"/eml/access\"). These default rules can be overridden for particular data entities by adding additional \ elements in the physical/distribution trees of those entities.