-
Notifications
You must be signed in to change notification settings - Fork 0
/
eml-210info.xml
603 lines (586 loc) · 27.1 KB
/
eml-210info.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<!--
'$RCSfile: eml-210info.xml,v $'
Copyright: 1997-2002 Regents of the University of California,
University of New Mexico, and
Arizona State University
Sponsors: National Center for Ecological Analysis and Synthesis and
Partnership for Interdisciplinary Studies of Coastal Oceans,
University of California Santa Barbara
Long-Term Ecological Research Network Office,
University of New Mexico
Center for Environmental Studies, Arizona State University
Other funding: National Science Foundation (see README for details)
The David and Lucile Packard Foundation
For Details: http://knb.ecoinformatics.org/
'$Author: obrien $'
'$Date: 2009-03-05 19:49:33 $'
'$Revision: 1.19 $'
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-->
<article class="faq">
<title>Information for EML 2.1.0 Document Authors</title>
<para/>
<para>
<ulink url="./index.html">EML Schema Documentation</ulink>
</para>
<para>
<ulink url="./eml-faq.html">EML FAQs</ulink>
</para>
<para> Several modifications to the EML schema made in version 2.1.0 will require changes to how
EML documents are structured, and these changes are highlighted here. EML authors should also
refer to the affected sections in the normative schema documents for complete usage
information and examples. Existing EML 2.0-series documents can be converted to EML 2.1.0
using the XSL stylesheet that accompanies this release, as described in section 2 below. </para>
<para> The EML 2.1.0 release addresses several errors with respect to W3C specifications
for XML schema (http://www.w3.org/TR/xml). Although the changes are small,
they are incompatible with EML 2.0.0 and 2.0.1 schemas, which necessitated advancing the
version number to "2.1". The STMML schema was also found to be invalid with respect to XML
Schema language, and the most reasonable fix for this bug also is incompatible with its earlier
versions. EML users should note that the STMML schema error was <emphasis>not</emphasis>
related to elements used directly by EML (i.e., <unitList> or <unitType>). However,
EML imports all of STMML, and
authors of EML documents may have made use of other parts of that schema. Therefore,
it was decided to advance the namespace used for STMML-related imports to "stmml-1.1",
in keeping with the EML version naming pattern. The STMML authors have been contacted,
and they are interested in our development and use of STMML. </para>
<para> Other features and enhancements were added to this release that represent significant
improvements. The XML data type requirements for several elements were changed, in some
cases to constrain their content, and in other cases to increase flexibility. The names of two
elements were changed to make them consistent throughout EML. In the literature schema two
elements became optional so that EML could accommodate in-press publications where
the volume and page range are not yet known. Support for two new optional elements was
also added: a 'contact' tree can now be used in the literature module, and a ‘descriptive’ element
can be used in distribution trees.</para>
<para> For the most part, EML 2.1.0 does not introduce major new features, or require a
shift in use or implementation. There was a deliberate decision to balance the impact on
instance document authors with necessary schema maintenance, and to prepare the schema
for the next phase of planned improvements and features. Some of the changes to EML 2.1.0
are invisible to document authors; see the 'Readme' that accompanies the distribution for a
complete list of the bugs addressed, and for information of interest to developers.</para>
<para> </para>
<!--
whats new in 2.1 -->
<section>
<title>Changes and New Features in EML 2.1.0</title>
<qandaset>
<qandaentry id="id.1">
<question>
<para>EML Schema validity</para>
</question>
<answer>
<para>EML allows authors to place any XML markup in
<additionalMetadata> sections at the end of the document. The content
model for <additionalMetadata> includes an optional <describes>
element so that references to EML nodes can be included as necessary.
In EML 2.0 this element was placed alongside the additional XML content;
however, this construct is not allowed in XML Schema, and the error was
not reported by XML parsers available at the time EML 2.0 was released.
In EML 2.1.0, the error has been corrected by adding a required child element
to the <additionalMetadata> section to contain the
"<xs:any>" XML content. </para>
<para><additionalMetadata> sections must include the child
<metadata> to contain the additional XML markup. The optional
<describes> element may still be included to reference a particular node
of the document. Multiple <describes> elements can be included if needed.
Examples of documents written against 2.1.0 and 2.0.1 are below. Also see the
<ulink url="eml.html#additionalMetadata">additionalMetadata normative documentation</ulink>.
</para>
<para> In EML 2.0.1, an additionalMetadata section looked like this: <programlisting><![CDATA[...
<additionalMetadata>
<describes>123</describes>
<unitList>
<unit name="speciesPerSquareMeter"
unitType="arealDensity"
id="speciesPerSquareMeter"
parentSI="numberPerSquareMeter"
multiplierToSI="1"/>
</unitList>
</additionalMetadata>...]]></programlisting>
</para>
<para> In EML 2.1.0, the markup must be enclosed within <metadata> tags: <programlisting><![CDATA[
...
<additionalMetadata>
<describes>123</describes>
<metadata>
<unitList>
<unit name="speciesPerSquareMeter"
unitType="arealDensity"
id="speciesPerSquareMeter"
parentSI="numberPerSquareMeter"
multiplierToSI="1"/>
</unitList>
</metadata>
</additionalMetadata>
...
]]></programlisting>
</para>
</answer>
</qandaentry>
<qandaentry id="id.2">
<question>
<para>STMML Schema validity</para>
</question>
<answer>
<para>EML makes use of the Scientific Technical and Medical Markup Language schema
(STMML, stmml.xsd) for describing units, and the STMML schema was also found to
be invalid. The error was not related to
elements used directly by EML (i.e., <unitList> or
<unitType>), however some authors may have used other parts of stmml.xsd
in their documents. The required schema changes were not compatible with STMML-1.0, and
the EML development group is working with the STMML developers on this
issue. Since EML now imports a version of STMML that is not identical to that available
from its authors, it was decided to advance the namespace used by EML 2.1.0 for stmml-related
files to "stmml-1.1". To import stmml.xsd into one of your EML 2.1.0 documents use the XML
namespace declaration for STMML in the code below: <programlisting><![CDATA[
<?xml version="1.0"?>
<eml:eml
packageId="eml.1.1" system="knb"
xmlns:eml="eml://ecoinformatics.org/eml-2.1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:stmml="http://www.xml-cml.org/schema/stmml-1.1"
xsi:schemaLocation="eml://ecoinformatics.org/eml-2.1.0 eml.xsd">
<dataset>
...
</dataset>
<additionalMetadata>
<metadata>
<stmml:unitList xmlns:stmml="http://www.xml-cml.org/schema/stmml-1.1"
xsi:schemaLocation="http://www.xml-cml.org/schema/stmml-1.1 stmml.xsd">
<stmml:unit name="gramsPerSquareMeter"
unitType="arealMassDensity"
id="gramsPerSquareMeter"
parentSI="kilogramsPerSquareMeter"
multiplierToSI=".001">
..
</stmml:unitList>
</metadata>
</additionalMetadata>
</eml:eml>
]]></programlisting>
</para>
</answer>
</qandaentry>
<qandaentry id="id.3">
<question>
<para>Location of Access Control Trees</para>
</question>
<answer>
<para>In EML 2.0.1 an <access> tree could be included in each top-level module (i.e. dataset,
citation, software, or protocol) to control access to the entire metadata document. Additionally, to
control access to individual entities,
some authors put <access> trees in <additionalMetadata> sections and used
<describes> elements to reference their <distribution> nodes.
Authors may have inferred that access
control could be applied to any node with this practice. However, node-level access
control is problematic to implement, and in practice only access trees that reference
distribution nodes are recognized (as was stated in EML 2.0.1 documentation).
A better solution is to locate <access> nodes above or near the node to
which the access rules should be applied. This feature has been added to
EML 2.1.0. </para>
<para> In EML 2.1.0, access trees can be placed in 2 locations. To control the entire
metadata document (i.e., "document-level access"), an <access> tree should
be placed as a child of the root element (<ulink url="eml.png">EML image</ulink>). If a
metadata author wishes to override the document-level control for a specific entity, an
additional access tree may be placed as the last child of a <distribution>
element within the <physical> tree of that entity
(<ulink url="eml-physicalDistribution.png">Physical Distribution Type image</ulink>).
The structure of the access module itself has not changed (<ulink url="eml-access.html">access
module documentation</ulink> ).</para>
<para>Example 1. To control access to all the metadata and by default to the data, use an
<access> element at the top level: <programlisting><![CDATA[
<eml:eml>
<access>
...
</access>
<dataset>
...
</dataset>
<additionalMetadata>
...
</additionalMetadata>
</eml:eml>
]]></programlisting>
</para>
<para>Example 2. Access rules can still be specified for any data entity by placing an
access tree under that entity's physical/distribution element. The following example
illustrates how a dataTable's access tree can be used to override permissions
set at the document level.
If no access is specified in distribution then the document-level access rules are
applied. </para>
<programlisting><![CDATA[
<eml:eml>
<dataset>
...
<dataTable>
...
<physical>
...
<distribution>
...
<access>
...
</access>
</distribution>
</physical>
...
</dataTable>
</dataset>
</eml:eml>
]]></programlisting>
</answer>
</qandaentry>
<qandaentry id="id.4">
<question>
<para>Typing of <gRing> corrected</para>
</question>
<answer>
<para>The content of the <gRing> element was retyped to make these nodes more usable. This
element is generally analogous to the FGDC component for ring. This element should now contain
a string comprised of a comma-delimited sequence of longitude and latitude values for vertex
coordinates (in decimal degrees), as in the example below. For more information, see the normative documents
for gRing in the <ulink url="eml-coverage.html#gRing">
coverage module</ulink>. <programlisting><![CDATA[
..
<gRing>-119.453,35.0 -125,37.5555 -122,40 -119.453,35.0 </gRing>
..
]]></programlisting>
</para>
</answer>
</qandaentry>
<qandaentry id="id.5">
<question>
<para>Entity Attributes: <bounds> minimum and maximum are of type
xs:float</para>
</question>
<answer>
<para>In EML 2.0.1, <bounds> elements were typed as
xs:decimal and did not support scientific notation. The base data type
was changed to 'xs:float' in EML 2.1.0 to accommodate both decimal and scientific
notation while maintaining backward compatibility. Authors should keep
in mind that there are still advantages to using decimal numbers for bounds,
because the decimal data type maintains precision during storage while
the floating point type does not. An alternative type, "precisionDecimal"
(corresponding to the IEEE type "floating-point decimal”), may be available
in the next version of XML Schema (i.e., v1.1, a working draft as of late 2008).
It combines features of both the decimal and float types in that it supports
the values and notation of a float, but is treated as decimal in arithmetic
and storage. The typing of this element may be changed to this new
type in a future release of EML. For more information, see the normative
documentation for <ulink url="eml-attribute.html#NumericDomainType">
NumericDomainType</ulink>.</para>
<para>In EML 2.1.0, bounds can be written as: <programlisting><![CDATA[
<attribute>
...
<numericDomain>
<numberType>real</numberType>
<bounds>
<minimum>0</minimum>
<maximum>1.234E15</maximum>
</bounds>
</numericDomain>
</attribute>
]]></programlisting>
</para>
</answer>
</qandaentry>
<qandaentry id="id.6">
<question>
<para>Geographic Coverage: <altitudeUnits> use Standard Units of
LengthType</para>
</question>
<answer>
<para>In EML 2.0.0 and 2.0.1, altitude units were typed as xs:string,
and EML authors were instructed to include a vertical datum along
with the unit. In EML 2.1.0 this has been revised. Altitudes are now
restricted to lengths in Standard Units (e.g. meter, foot, etc), and the
datum should be included as part of the textual geographicDescription element. Document
authors should note that including any additional content in the
<altitudeUnits> element other than a length value, such as the datum,
is not valid in EML 2.1.0. For a list of allowable units, see <ulink url="eml-coverage.html#altitudeUnits">
the normative description for <altitudeUnits></ulink>. <programlisting><![CDATA[
..
<boundingCoordinates>
...
<boundingAltitudes>
<altitudeMinimum>0</altitudeMinimum>
<altitudeMaximum>120</altitudeMaximum>
<altitudeUnits>meter</altitudeUnits>
</boundingAltitudes>
</boundingCoordinates>
..
]]></programlisting>
</para>
</answer>
</qandaentry>
<qandaentry id="id.7">
<question>
<para>Geographic Coverage: Latitude and Longitude are type xs:decimal, with appropriate
ranges</para>
</question>
<answer>
<para>In EML 2.0.1, latitude and longitude values in <geographicCoverage>
elements were typed as a xs:string. In EML 2.1.0 these values are restricted to
decimal numbers with realistic ranges (-90 to 90, and -180 to 180, respectively).
Fractions of a degree in minutes and seconds should be converted to decimal
format, and strings denoting direction or hemisphere (e.g., 'S' or 'south') are not
allowed. South latitudes and west longitudes must be indicated by a minus
sign (-) in front of the coordinate, as in the example below. These constraints
are consistent with the intended use of this field, which is to support mapping
the general geographic coverage of EML resources. Authors should keep in
mind that very specific descriptions of spatial data can be accommodated by
EML modules dedicated to that purpose. More information on bounding coordinates can
be found in the <ulink url="eml-coverage.html#boundingCoordinates">normative technical
documents</ulink>.<programlisting><![CDATA[
..
<boundingCoordinates>
<westBoundingCoordinate>-120.2534</westBoundingCoordinate>
<eastBoundingCoordinate>-119.7550</eastBoundingCoordinate>
<northBoundingCoordinate>34.2231</northBoundingCoordinate>
<southBoundingCoordinate>34.1231</southBoundingCoordinate>
</boundingCoordinates>
..
]]></programlisting>
</para>
</answer>
</qandaentry>
<qandaentry id="id.8">
<question>
<para>Element content must be non-empty</para>
</question>
<answer>
<para>In EML 2.0.1, elements of the string data type were allowed to be
empty or contain only whitespace. This feature
was occasionally exploited as a work-around to force incomplete documents
to validate in XML editors and the Metacat harvester, but this practice may
cause problems in document parsing or for EML tools such as Kepler.
In EML 2.1.0, string content is now typed as "NonEmptyString" and string
entities are required to have minimal non-whitespace content. So, whereas the following
content would have been allowed in EML 2.0.1: <programlisting><![CDATA[
...
<mediumName> </mediumName>
...
]]>
or
<![CDATA[
...
<attributeName/>
...
]]></programlisting>
</para>
<para>In EML 2.1.0, empty (or whitespace) content is not allowed. Actual content must be
provided. <programlisting><![CDATA[
...
<attributeName>approx. temperature</attributeName>
...
]]></programlisting>
</para>
</answer>
</qandaentry>
<qandaentry id="id.9">
<question>
<para>An offline resource has a minimum of one element required
(<mediumName>) </para>
</question>
<answer>
<para>In EML 2.0.1, an author could describe an offline data resource, but include no
information about the resource's distribution. In EML-2.1.0, minimal content (one
element) is now required. </para>
<para> In EML 2.0.1, the distribution tree for an offline resource could have ended with
no content: <programlisting><![CDATA[
...
<distribution>
<offline/>
</distribution>
...
]]></programlisting>
</para>
<para> In EML 2.1.0, the element <mediumName> is required: <programlisting><![CDATA[
...
<distribution>
<offline>
<mediumName>Atlas of Lake Erie Shorelines</mediumName>
</offline>
</distribution>
...
]]></programlisting>
</para>
</answer>
</qandaentry>
<qandaentry id="id.10">
<question>
<para>Methods elements are standardized to <methods></para>
</question>
<answer>
<para>In EML 2.0.1, both "<method>" and "<methods>" elements were included
in the schema, which caused confusion for some authors. In EML
2.1.0, instances of the MethodsType have been standardized to
"methods". </para>
<para>In EML 2.0.1, this path existed: <programlisting><![CDATA[
...
/eml/dataset/dataTable/attribute/method/
...
]]></programlisting>
</para>
<para>In EML 2.1.0, this path is now properly constructed as: <programlisting><![CDATA[
...
/eml/dataset/dataTable/attribute/methods/
...
]]></programlisting>
</para>
</answer>
</qandaentry>
<qandaentry id="id.11">
<question>
<para>Elements for date-time have been standardized to <dateTime></para>
</question>
<answer>
<para>In EML 2.0.1, both "<datetime>" and
"<dateTime>" elements were included, which caused confusion for some authors. In EML
2.1.0, these instances have been standardized to "dateTime". </para>
<para>In EML 2.0.1, this path existed: <programlisting><![CDATA[
...
/eml/dataset/dataTable/attribute/measurementScale/datetime/
...
]]></programlisting>
</para>
<para>In EML 2.1.0, this path is now properly constructed as: <programlisting><![CDATA[
...
/eml/dataset/dataTable/attribute/measurementScale/dateTime/
...
]]></programlisting>
</para>
</answer>
</qandaentry>
<qandaentry id="id.12">
<question>
<para>For journal articles, the elements <volume> and
<pageRange> are now optional</para>
</question>
<answer>
<para>Two elements describing journal articles in the literature schema (eml-literature.xsd),
<volume> and <pageRange>, are now optional to permit
articles-in-press to be described in EML.</para>
</answer>
</qandaentry>
<qandaentry id="id.13">
<question>
<para>A Citation may have an optional <contact> tree</para>
</question>
<answer>
<para>Also in eml-literature.xsd, an optional <contact> tree has been added
to permit a contact to be designated for a publication. For example, a contact
could be provided for reprint requests.
<programlisting/>
</para>
</answer>
</qandaentry>
<qandaentry id="id.14">
<question>
<para>New optional element (<onlineDescription>) for a description of an
online resource</para>
</question>
<answer>
<para>A new element, <onlineDescription>, was added to support providing
a brief description of
the content of an online element's child. This optional element is available for both
resource-level and physical-level distribution nodes, and is typed as a
NonEmptyString. One possible use for the description is to provide optional content for
the HTML anchor element that accompanies a URL. <programlisting/>
</para>
</answer>
</qandaentry>
</qandaset>
</section>
<!--
converting your eml -->
<section>
<title>Converting EML documents from v2.0.0/1 to v2.1.0</title>
<qandaset>
<qandaentry>
<question>
<para>About the EML conversion stylesheet</para>
</question>
<answer>
<para>An XSL stylesheet is provided with the EML Utilities
to convert valid EML 2.0-series documents to EML 2.1.0 (see
<ulink url="http://knb.ecoinformatics.org/software/eml/">http://knb.ecoinformatics.org/software/eml/</ulink>).
The stylesheet performs basic tasks to create a
template EML 2.1.0 document (below). For more information, see the Utilities documentation.
<orderedlist>
<listitem>
<para>Updates namespaces to eml-2.1.0 and stmml-1.1</para>
</listitem>
<listitem>
<para>Encloses XML markup within <additionalMetadata> sections in
<metadata> tags</para>
</listitem>
<listitem>
<para>Renames elements whose spelling has changed (<method> and <datetime>)</para>
</listitem>
<listitem>
<para>Copies access trees from <additionalMetadata> to other parts of the document (for common
constructs)</para>
</listitem>
<listitem>
<para>Optionally replaces the content of the "packageId" attribute on the root
element, <eml:eml>, using a parameter</para>
</listitem>
</orderedlist>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Validity of new EML 2.1.0 documents</para>
</question>
<answer>
<para>
Because of the flexibility allowed in EML, the stylesheet may encounter EML 2.0.1 structures that
cannot be transformed or that may result in invalid EML 2.1.0 after processing.
For example, by design <additionalMetadata> sections are parsed laxly, and
so it is possible for their content in EML-2.0.0/1 to contain <access> trees
which are invalid. Also, the content of several elements has been more tightly
constrained in EML 2.1.0 (e.g., latitude and longitude), and data types are not
detectable by a stylesheet. Document authors are advised to check the validity of
their new EML 2.1.0 after transformation. EML instance documents
can be validated in these ways: <orderedlist>
<listitem>
<para>With the <ulink url="http://knb.ecoinformatics.org/emlparser/ ">online EML
Parser</ulink>. The online parser will validate all versions of EML.
</para>
</listitem>
<listitem>
<para>Using the Parser that comes with EML. To execute it, change into the 'lib'
directory of the EML release and run the 'runEMLParser' script passing your EML
instance file as a parameter. The script performs two actions: it checks the validity of references
and id attributes, and it validates the document against the EML 2.1 schema.
The EML parser included with the distribution is capable of checking only EML 2.1.0 documents, and
<emphasis>cannot</emphasis> be used to validate earlier versions (e.g., EML 2.0.1).
</para>
</listitem>
<listitem>
<para>If you are planning to contribute your EML 2.1.0 document to a Metacat repository, note
that the Metacat servlet checks all versions of incoming EML for validity as part of the insertion process.
</para>
</listitem>
</orderedlist>
</para>
</answer>
</qandaentry>
</qandaset>
<para> </para>
</section>
</article>