Skip to content

Commit

Permalink
Removed module description text from schemas.
Browse files Browse the repository at this point in the history 
This text is now in the specification document in "docs".
  • Loading branch information
@mbjones
mbjones committed Nov 22, 2018
1 parent f5ef47f commit 4ca6efd
Show file tree
Hide file tree
Showing 23 changed files with 831 additions and 1,453 deletions.
201 changes: 17 additions & 184 deletions xsd/eml-access.xsd
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:doc="eml://ecoinformatics.org/documentation-2.2.0"
xmlns:res="eml://ecoinformatics.org/resource-2.2.0"
xmlns="eml://ecoinformatics.org/access-2.2.0"
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:doc="eml://ecoinformatics.org/documentation-2.2.0"
xmlns:res="eml://ecoinformatics.org/resource-2.2.0"
xmlns="eml://ecoinformatics.org/access-2.2.0"
targetNamespace="eml://ecoinformatics.org/access-2.2.0">
<xs:import namespace="eml://ecoinformatics.org/documentation-2.2.0"
<xs:import namespace="eml://ecoinformatics.org/documentation-2.2.0"
schemaLocation="eml-documentation.xsd"/>
<xs:import namespace="eml://ecoinformatics.org/resource-2.2.0"
<xs:import namespace="eml://ecoinformatics.org/resource-2.2.0"
schemaLocation="eml-resource.xsd"/>
<xs:annotation>
<xs:documentation>
Expand Down Expand Up @@ -50,173 +50,6 @@
<title>
The eml-access module - Access control rules for resources
</title>
<para>
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.
</para>
<para>
There are two mechanisms for including access control
via the eml-access module:
<orderedlist>
<listitem>
<para>
The top-level "eml" element may have an optional
&lt;access&gt; 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 &lt;access&gt; element
(see below), access to data entities will be controlled by
the package-level &lt;access&gt; element in the
&lt;eml&gt; element.
</para>
</listitem>
<listitem>
<para>
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 &lt;inline&gt;
element, as well as resources that are referenced by the
&lt;online/url&gt; and &lt;online/connection&gt; 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.
</para>
</listitem>
</orderedlist>
</para>
<para>
In previous versions of EML access rules for entity-level
distribution were contained in &lt;additionalMetadata&gt;
sections and referenced via the &lt;describes&gt; 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.
</para>
<para>
Access is specified with a choice of child elements, either
&lt;allow&gt; or &lt;deny&gt;. Within these rules, values can
be assigned for each &lt;principal&gt; using the
&lt;permission&gt; element. Users given &quot;read&quot; permission can
view the resource; &quot;write&quot; allows changes to the resource
excluding changes to the access rules; &quot;changePermission&quot;
includes &quot;write&quot; plus the changing of access rules. Users
allowed &quot;all&quot; permissions; may do all of the above. Access to
data and metadata is affected by the order attribute of the
&lt;access&gt; 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 &quot;allowFirst&quot;, and there are rules
similar to the following (with non-critical sections deleted):
<literalLayout>
&lt;deny&gt;
&lt;principal&gt;public&lt;/principal&gt;
&lt;permission&gt;read&lt;/permission&gt;
&lt;/deny&gt;
&lt;allow&gt;
&lt;principal&gt;uid=alice,o=NASA,dc=ecoinformatics,dc=org&lt;/principal&gt;
&lt;permission&gt;read&lt;/permission&gt;
&lt;/allow&gt;
</literalLayout>
the principal &quot;uid=alice ...&quot; will be denied access,
because it is a member of the special &quot;public&quot;
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 &quot;denyFirst&quot;, and the
allow rule will override the deny rule when it is processed
second.
</para>
<para>
An example is given below, with non-critical sections deleted:
<literalLayout>
&lt;eml&gt;
&lt;access
authSystem="ldap://ldap.ecoinformatics.org:389/dc=ecoinformatics,dc=org"
order="allowFirst"&gt;
&lt;allow&gt;
&lt;principal&gt;uid=alice,o=NASA,dc=ecoinformatics,dc=org&lt;/principal&gt;
&lt;permission&gt;read&lt;/permission&gt;
&lt;permission&gt;write&lt;/permission&gt;
&lt;allow&gt;
&lt;/access&gt;
&lt;dataset&gt;
...
...
&lt;dataTable id="entity123"&gt;
...
&lt;physical&gt;
...
&lt;distribution&gt;
...
&lt;access id="access123"
authSystem="ldap://ldap.ecoinformatics.org:389/dc=ecoinformatics,dc=org"
order="allowFirst"&gt;
&lt;deny&gt;
&lt;principal&gt;uid=alice,o=NASA,dc=ecoinformatics,dc=org&lt;/principal&gt;
&lt;permission&gt;write&lt;/permission&gt;
&lt;/deny&gt;
&lt;/access&gt;
&lt;/distribution&gt;
&lt;/physical&gt;
&lt;/dataTable&gt;
&lt;dataTable id="entity234"&gt;
...
&lt;physical&gt;
...
&lt;distribution&gt;
...
&lt;access&gt;
&lt;references&gt;access123&lt;/references&gt;
&lt;/access&gt;
&lt;/distribution&gt;
&lt;/physical&gt;
&lt;/dataTable&gt;
...
&lt;/dataset&gt;
&lt;eml&gt;
</literalLayout>
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 &quot;entity123&quot; and
&quot;entity234&quot;, 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.
</para>
<para>
This example also shows how the eml-access module, like other modules,
may be "referenced" via the &lt;references&gt; 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.
</para>
<para>
In summary, access rules can be applied in two places in an
eml document. Default access rules are established
in the top &lt;access&gt; element for the main eml document (e.g.,
"/eml/access"). These default rules can be overridden
for particular data entities by adding additional &lt;access&gt;
elements in the physical/distribution trees of those entities.
</para>
</section>
</doc:moduleDescription>
<doc:recommendedUsage>all data where controlling user access to the
Expand All @@ -232,9 +65,9 @@
<doc:summary>The rules defined in this element will determine the level
of access to a resource for the defined users and groups.</doc:summary>
<doc:description>The access element contains a list of rules defining
permissions for this resource. For descriptions of the individual elements,
see the AccessType.The permission rules defined here can be overridden
by rules added to an access tree in the PhysicalDistributionType
permissions for this resource. For descriptions of the individual elements,
see the AccessType.The permission rules defined here can be overridden
by rules added to an access tree in the PhysicalDistributionType
at the entity level. </doc:description>
<doc:example>See the description of the AccessType.</doc:example>
</xs:appinfo>
Expand All @@ -248,11 +81,11 @@
of access to a resource for the defined users and groups.</doc:summary>
<doc:description>The access element contains a list of rules that define
the level of access for a resource. There are two uses of access trees: to
control access to either metadata or data. To control access to metadata
use the eml/access tree. By default, these rules will also apply to the contained
data. To override the default controls for specific data entities, use the
access element available in the entity's physical/distribution tree. A
combination of access trees and their "order rules" (see description of
control access to either metadata or data. To control access to metadata
use the eml/access tree. By default, these rules will also apply to the contained
data. To override the default controls for specific data entities, use the
access element available in the entity's physical/distribution tree. A
combination of access trees and their "order rules" (see description of
the "order" attribute) allows EML authors
to have fine control over permissions for individuals and groups.
</doc:description>
Expand Down Expand Up @@ -297,12 +130,12 @@
<doc:tooltip>Rule order</doc:tooltip>
<doc:summary>The order in which the allow and deny rules should be
applied.</doc:summary>
<doc:description>To obtain the desired access control, use the order
<doc:description>To obtain the desired access control, use the order
attribute to define which rules should be applied first. The acceptable
values are 'allowFirst' and 'denyFirst'. If 'allowFirst' is
specified, then all 'allow' rules are processed, and then overridden
by all 'deny' rules. If 'denyFirst' is specified, then all 'deny'
rules are processed, and then overridden by all 'allow' rules.
rules are processed, and then overridden by all 'allow' rules.
</doc:description>
<doc:example>allowFirst</doc:example>
</xs:appinfo>
Expand Down Expand Up @@ -384,7 +217,7 @@
<para>'changePermission' - modifications including access rules, and </para>
<para>'all' - all of the above. </para>
<para>

This element also allows other permission values that may be applicable to some other authentication systems but are not defined in this specification (if these other values are used, access rule enforcement is indeterminate outside of the originating system).</para>
</doc:section>
</doc:description>
Expand Down
Loading

0 comments on commit 4ca6efd

Please sign in to comment.