Merge pull request #96 from OpenGeoMetadata/schema-groups

URI to Field Name and minor copyedits

Author: karenmajewicz

docs/aardvark-gbl-1-crosswalk.md

@@ -7,7 +7,7 @@ The following chart shows the full Aardvark schema and which GBL 1.0 fields can
 
 ## Elements without a crosswalk
 
-Most of the elements from GBL 1.0 can be crosswalked directly into OGM Aardvark. The values for these elements are the same - only the URI name has changed or the field has been converted to an array.  
+Most of the elements from GBL 1.0 can be crosswalked directly into OGM Aardvark. The values for these elements are the same - only the field name has changed or the field has been converted to an array.  
 
 However, there are three elements in GBL 1.0 that do not directly translate into OGM Aardvark. While they have been replaced with similar fields in OGM Aardvark, the **values themselves** would need to be altered during crosswalking.
 
@@ -24,4 +24,4 @@ However, there are three elements in GBL 1.0 that do not directly translate into
 **Is Part Of (`dct_isPartOf_sm`)**
 
 * GBL 1.0 Description: This multi-valued GBL 1.0 plain text field is for writing out the name of a collection. Example: `dct_isPartOf_sm:"Village Maps of India"`
-* Similar Aardvark element: The URI is the same in Aardvark, but it is now a non-literal field. The value must be one or more IDs that reference another record within the system. Example: `dct_isPartOf_sm:"princeton-z603r079s"`
+* Similar Aardvark element: The field name is the same in Aardvark, but it is now a non-literal field. The value must be one or more IDs that reference another record within the system. Example: `dct_isPartOf_sm:"princeton-z603r079s"`

docs/about-ogm-aardvark.md

@@ -15,9 +15,9 @@ Details about the OpenGeoMetadata metadata schema, OGM Aardvark
 *   **GBL 1.0**: The legacy metadata schema designed for GeoBlacklight versions 2.0-3.7. [The schema is documented on this Legacy page.](gbl-1.0.md)
 *   **OGM Aardvark**: The new metadata schema that is compatible with GeoBlacklight version 4.0.
 *   **GeoBlacklight**: When spelled out, GeoBlacklight refers to [the application itself](https://geoblacklight.org), not its namesake legacy metadata schema, GBL 1.0.
-*   **URI**: This is the name we give to the metadata element itself. For example, the URI for the Subject field is `dct_subject_sm`. 
-*   **Namespace**: This is how we signify which family of standards or schemas an element belongs to. For the GeoBlacklight schema, this takes the form of the URI’s prefix. For the URI `dct_subject_sm`,  `dct_` is the prefix and signifies that this element is from Dublin Core.
-*   **Solr field type**: This is the suffix appended to the URI and indicates what kind of Solr field should be indexed. For `dct_subject_sm`, the `_sm` stands for String Multiple. It indicates that the field type is a string and that it can have multiple values.
+*   **Field name**: This is the name we give to the metadata element itself. For example, the field name for the Subject field is `dct_subject_sm`.
+*   **Namespace**: This is how we signify which family of standards or schemas an element belongs to. For the GeoBlacklight schema, this takes the form of the field name's prefix. For `dct_subject_sm`,  `dct_` is the prefix and signifies that this element is from Dublin Core.
+*   **Solr field type**: This is the suffix appended to the field name and indicates what kind of Solr field should be indexed. For `dct_subject_sm`, the `_sm` stands for String Multiple. It indicates that the field type is a string and that it can have multiple values.
 *   **Value**: This is the information that is entered in a field. It may be free text (literal value) or a URI/code (nonliteral value).
 
 OGM Aardvark is a discovery metadata schema for geospatial resources. It was intentionally developed with cross-application in mind and can be used to describe geospatial assets of all kinds.
@@ -56,7 +56,7 @@ The minimal nature of the original GeoBlacklight schema combined with the growin
 
 The new set of rights elements are:
 
-| Label              | URI                     | Description and Entry Guidelines |
+| Label              | Field Name                     | Description and Entry Guidelines |
 |:-------------------|:------------------------|:---------------------------------|
 | Access Rights      | `dct_accessRights_s`    | One of two possible values, "Public" or "Restricted"; controls whether a user can preview or download an item. This element replaces `dc_rights_s`. |
 | Rights             | `dct_rights_sm`         | Free-text field for generic, catch-all access and usage rights. Can include clickable links. |
@@ -73,7 +73,7 @@ GeoBlacklight version 3.4 and earlier has an Item Relations widget that displays
 
 The new set of relationship elements are:
 
-| Label              | URI                     | Description and Entry Guidelines |
+| Label              | Field Name                     | Description and Entry Guidelines |
 |:-------------------|:------------------------|:---------------------------------|
 | Source             | `dct_source_sm`         | For items that have been derived from another item (e.g. a digitized shapefile from a historical map). |
 | Is Part Of         | `dct_isPartOf_sm`       | For items that are a subset of another item (e.g. a page in a book). This value type is changing from free-text in Version 1.0 to an ID (slug) in the new schema. |
@@ -84,7 +84,7 @@ The new set of relationship elements are:
 | Relation            | `dct_relation_sm`      | For a general purpose relation.  |
 
 
-#### Consistent namespaces for all metadata element URIs
+#### Consistent namespaces for all metadata element field names
 
 OGM Aardvark gives preference to elements found in established schemas over custom fields.
 
@@ -96,7 +96,7 @@ OGM Aardvark gives preference to elements found in established schemas over cust
 
 #### Multivalued elements whenever possible
 
-The original schema features several descriptive metadata fields that only accept one value. The new schema expands many of these to multiple. This changes the URI suffix from `_s` to` _sm`. Although it will not affect the GeoBlacklight functionality, this practice may conflict with indexing, as Solr will treat `dct_publisher_s` as a different field than `dct_publisher_sm`.
+The original schema features several descriptive metadata fields that only accept one value. The new schema expands many of these to multiple. This changes the field name suffix from `_s` to` _sm`. Although it will not affect the GeoBlacklight functionality, this practice may conflict with indexing, as Solr will treat `dct_publisher_s` as a different field than `dct_publisher_sm`.
 
 #### More intuitive name for unique key
 
@@ -158,6 +158,3 @@ Refinements to OpenGeoMetadata have continued through the work of the ongoing Me
 * Lena Denis (Johns Hopkins University)
 * Marc McGee (Harvard University)
 * Rebecca Seifried (UMass Amherst)
-
-
-

docs/create-metadata.md

@@ -1,8 +1,8 @@
-# Creating Metadata
+# Create Metadata
 How to create metadata records in the OpenGeoMetadata schema
 
 
-## Authoring
+## Author new metadata
 
 Step 1 of the metadata workflow is to create or collect original metadata for each layer. Depending upon the type of resource and a repository’s chosen workflows, the format of the original metadata may be in different standards or schemas.
 
@@ -16,7 +16,7 @@ The most commonly used tool for creating geospatial metadata is Esri’s ArcCata
 
 **Option B: Create metadata in the OGM schema directly**
 
-Other repositories skip Option A and create records directly in the OpenGeoMetadata metadata schema. Although users benefit from the more complete information that can be added to an FGDC or ISO document, these standards are not needed to run GeoBlacklight. These repositories often use a spreadsheet or a Dublin-Core-based metadata editor to create the records. Scripts can be used to convert spreadsheets (in .csv format) to JSON in the OpenGeoMetadata schema. See [Workflows and Tools](/workflows-and-tools.md) for example scripts.
+Other repositories skip Option A and create records directly in the OpenGeoMetadata metadata schema. Although users benefit from the more complete information that can be added to an FGDC or ISO document, these standards are not needed to run GeoBlacklight. These repositories often use a spreadsheet or a Dublin-Core-based metadata editor to create the records. Scripts can be used to convert spreadsheets (in .csv format) to JSON in the OpenGeoMetadata schema. See [Metadata Processing Scripts](../scripts) for example scripts.
 
 ### For resources with existing metadata files
 
@@ -31,42 +31,32 @@ A large amount of publicly available geospatial data does not have ISO or FGDC.
 
 Scanned maps from library catalogs should have MARC catalog records, and they should be able to supply the repository with metadata in the .MRC or MARC XML file format.
 
-## Transforming
+---
+
+## Transform existing metadata
 
 If the metadata records are in a non-OpenGeoMetadata standard, the next step is to convert or transfer information from some or all of the fields to the OpenGeoMetadata schema. The result of this process is one or more JSON files that will be parsed and indexed by Solr. These JSON files will serve as the content to be shown in the GeoBlacklight application.
 
 ### Transformation workflows
 
-
-Most institutions have their own unique set of tools and workflows to perform this transformation.  These workflows may differ depending on the type of item to be referenced.  In most cases, automation of this process is desired, although it is possible to create the JSON files manually.
-
-The process, whether automated or manual, typically involves parsing the existing metadata record, extracting the values from selected fields and inserting the value into a new JSON document under the corresponding OpenGeoMetadata schema field. In most cases the values can simply be copied over as is, although some additional formatting may be necessary.
-
-See [Metadata Scripts](scripts.md) to view custom scripts and tools for additional metadata authoring techniques.
-
 !!! tip
 
-	* The JSON files in the OpenGeoMetadata schema do not need to be stored with the data/items they are referencing.
+	* JSON files in the OpenGeoMetadata schema do not need to be stored with the data/items they are referencing.
 	* Multiple items can be referenced in a single JSON file.
 	* Some fields will contain the same values for each item (e.g. `gbl_mdVersion_s`)
+	* See [Metadata Processing Scripts](../scripts) to view custom scripts and tools for additional metadata authoring techniques.
 
-### Example
-
-
-A finished metadata file could look like the following example in ISO 19139 format:
-
-![ISO Metadata ](images/ISO_snippet.png)
+Most institutions have their own unique set of tools and workflows to perform this transformation.  These workflows may differ depending on the type of item to be referenced.  In most cases, automation of this process is desired, although it is possible to create the JSON files manually.
 
-The process of transforming metadata from the above formats to the OpenGeoMetadata schema involves mapping or “crosswalking” fields from one format to another.
+The process, whether automated or manual, typically involves parsing the existing metadata record, extracting the values from selected fields and inserting the value into a new JSON document under the corresponding OpenGeoMetadata schema field. This process is called mapping or "crosswalking." In most cases the values can simply be copied over as is, although some additional formatting may be necessary.
 
 ![ISO to GBL Crosswalk](images/ISO-GBL.jpg)
 
-
-## Example workflow
+### Example
 
 At Stanford, the [metadata records](https://github.com/OpenGeoMetadata/edu.stanford.purl) are natively authored in ESRI ArcCatalog and then transformed into ISO 19139. The ISO 19139 records are then transformed to MODS for the library catalog and GeoBlacklight for the [GeoBlacklight catalog](https://earthworks.stanford.edu/).
 
 ![Stanford Metadata Workflow](images/metadata_workflow.png)
 _Stanford University Metadata Workflow_
 
-Take, for example, the [metadata for this layer](https://github.com/OpenGeoMetadata/edu.stanford.purl/tree/master/rf/385/pb/1942). It has the [ISO 19139](https://github.com/OpenGeoMetadata/edu.stanford.purl/blob/master/rf/385/pb/1942/iso19139.xml) version of the metadata, along with the Feature Catalog (in [ISO 19110](https://github.com/OpenGeoMetadata/edu.stanford.purl/blob/master/rf/385/pb/1942/iso19110.xml)). We also have the transformation into [MODS](https://github.com/OpenGeoMetadata/edu.stanford.purl/blob/master/rf/385/pb/1942/mods.xml) and to [GeoBlacklight](https://github.com/OpenGeoMetadata/edu.stanford.purl/blob/master/rf/385/pb/1942/geoblacklight.json), as well as a [preview image](https://github.com/OpenGeoMetadata/edu.stanford.purl/blob/master/rf/385/pb/1942/preview.jpg). In some cases, you may even have an [HTML](http://opengeometadata.stanford.edu/metadata/edu.stanford.purl/druid:rv980rt5057/iso19139.html) version of the metadata for someone to read.
+Take, for example, the [metadata for this layer](https://github.com/OpenGeoMetadata/edu.stanford.purl/tree/master/rf/385/pb/1942). It has the [ISO 19139](https://github.com/OpenGeoMetadata/edu.stanford.purl/blob/master/rf/385/pb/1942/iso19139.xml) version of the metadata, along with the Feature Catalog (in [ISO 19110](https://github.com/OpenGeoMetadata/edu.stanford.purl/blob/master/rf/385/pb/1942/iso19110.xml)). We also have the transformation into [MODS](https://github.com/OpenGeoMetadata/edu.stanford.purl/blob/master/rf/385/pb/1942/mods.xml) and to [GeoBlacklight](https://github.com/OpenGeoMetadata/edu.stanford.purl/blob/master/rf/385/pb/1942/geoblacklight.json), as well as a [preview image](https://github.com/OpenGeoMetadata/edu.stanford.purl/blob/master/rf/385/pb/1942/preview.jpg). In some cases, you may even have an [HTML](http://opengeometadata.stanford.edu/metadata/edu.stanford.purl/druid:rv980rt5057/iso19139.html) version of the metadata for someone to read.