more docs

docs/exporting-and-exposing.md

@@ -10,7 +10,7 @@ With Tainacan you have the possibility to map your collection structure to one o
 
 You do it by informing, for each field you create, what is it relative in each format you want to map your collection to. You may sau for example, that you "Name" Field is the equivalent to the dc:Title attribute in Dublin Core and some another attribute in other format you choose.
 
-Tainacan is shipped with some Mapping standards that implement popular metadata standards. And it will be easy to create new standards.
+Tainacan is shipped with some Mapping standards that implement popular metadata standards. And it will be easy to create new standards.  See more [details about mapping standards](mapping-standards.md).
 
 Note: When you use a preset to build your collection, chances are that the mapping is already done. This is a good reason to consider using presets ;)
 
@@ -28,9 +28,9 @@ Tainacan makes it very easy to developers to create new exporters and publish th
 
 Tainacan is powered with an API that allows other applications to search and consume the content of your repository. By default, this API serves the content in JSON format, preserving the fields in the collections the way you created them.
 
-In the same way you can choose the format of the file when you export your collection, one can choose the format they want to consume yout content in. This is the role of exposers.
+In the same way you can choose the format of the file when you export your collection, one can choose the format he/she want to consume yout content in. This is what exposers are for.
 
-Each exposer implements a different way of presenting your data in the API response, and may support one or many mappings.
+Each exposer implements a different way of presenting your data in the API response, and may support one or many mappings. See more [details about exposers](exposers.md).
 
 For example, the default JSON exposer supports any mapping and can serve your content exposing any metadata standard you mapped your content to. The decision is in the hands of the application that makes the request to your API.
 

docs/exposers.md

@@ -0,0 +1,25 @@
+# Exposers
+
+Exposers are declarations and methods that expose the items of your repository in a certain way.
+
+## Structure
+
+### Name
+
+The name of the Exposer.
+
+### Slug
+
+A URL friendly version of the Exposer name, to be used as a parameter to the API request informing you want to get the data using this exposer.
+
+
+### Supported Mapping Standard
+
+A list of mapping standards that is exposer supports. This means that whenever someone makes a request to receive that via this exposer, he/she will also be able to choose in which mapping standar they want the content to be served.
+
+
+### Methods
+
+Every exposer have to implement PHP methods that will build the API response. 
+
+Optionally, an exposer can also implement a method to print data in the `HEAD` section of the HTML when visiting an item page. For example, JSON-LD exposer can add a JSON-LD object to the head of the page of every item in your collection.

docs/mapping-standards.md

@@ -0,0 +1,79 @@
+# Mapping Standards
+
+Mapping Standards are declarations of standards of metadata. Once they are available and activated in your repository, you can map the fields of your collections to them.
+
+## Structure
+
+A Mapping Standard has the following attributes.
+
+### Name
+
+The name of the Mapping Standard.
+
+### Fields
+
+A list of fields, terms or attributes that this mapping have. These are the element you will be able to map your Collection's Fields.
+
+Each field has the following attributes:
+
+* Name - The field name, that refers to the name of the attribute in the origin vocabulary or ontology (e.g. title)
+* Label - The human readable name
+* URI - The URI of this term/attribute in the origin Ontoloy/Vocabulary
+
+
+### Allow additional custom fields
+
+Boolen indicating wether this mapping allows additional custom fields to be added.
+
+### Context URL / Vocab URL
+
+The URL of the Ontology or vocabulary. For example `http://schema.org` or  `http://dublincore.org/documents/dcmi-terms/`
+
+### Type
+
+The Class of the ontology that this mapping refers to. For example `CreativeWork`, which is a class of Schema.org.
+
+## Examples
+
+```
+{
+	'name': 'Dublin Core',
+	'fields': {
+		{
+			'name': 'title',
+			'label': 'Title',
+			'URI': 'http://purl.org/dc/terms/title'
+		},
+		{
+			'name': 'publisher',
+			'label': 'Publisher',
+			'URI': 'http://dublincore.org/documents/dcmi-terms/'
+		},
+		... And so on...
+	},
+	'allow_extra_fields': true,
+	'context_url': ''
+}
+```
+
+```
+{
+	'name': 'Schema.org Creative Works',
+	'fields': {
+		{
+			'name': 'name',
+			'label': 'Name',
+			'URI': 'http://schema.org/name'
+		},
+		{
+			'name': 'alternativeHeadline',
+			'label': 'Alternative Headline',
+			'URI': 'http://schema.org/alternativeHeadline'
+		},
+		... And so on...
+	},
+	'allow_extra_fields': false,
+	'context_url': 'http://schema.org',
+	'type': 'CreativeWork'
+}
+```