Merge pull request #32 from OpenAgFunding/rs_iati_tag_extension

RS IATI tag extension

docs/extensions.md

@@ -0,0 +1,79 @@
+# Extensions
+
+The `tag` extension allows you to provide multiple classification of an aid activity to support **discovery** of relevant activities through search and browse interfaces. 
+
+It is based on the IATI [sector](http://iatistandard.org/202/activity-standard/iati-activities/iati-activity/sector/) element, but differs in that it _cannot_ be used to express statistical information about the share of a project budget or spend allocated to the topic of the tag. 
+
+### What is it?
+
+This new element looks a lot like the existing [sector](http://iatistandard.org/202/activity-standard/iati-activities/iati-activity/sector/) element, but without a percentage:
+
+```xml
+<openag:tag vocabulary="99" vocabulary-uri="http://aims.fao.org/aos/agrovoc/" code="c_4397">
+    <narrative @xml:lang="en">Livestock</narrative>
+</openag:tag>
+```
+
+> NB: the 'openag:' at the start of the element is because this element is currently available via an an extension. If tag is adopted as a core part of IATI 2.03 the element name will simply be `<tag>`, and the namespace declaration detailed below can be dropped. 
+
+**Values**:
+
+* the `@code` attribute will change use by use, but must always be included.
+* the `@vocabulary` attribute is '99' to specify that it's a custom vocabulary (as opposed to one of IATI's embedded ones).
+* the `@vocabulary-uri` should always be "http://aims.fao.org/aos/agrovoc/" for OpenAg early adopters, as they will be using the AGROVOC vocabulary, but in principle this can be used with any codelist.
+* the `<narrative>` should be included to show users what the code means, but will changed depending on the `@code` attribute.
+
+### How to include it?
+
+At the top of the `<iati-activities>` if using throughout a file, or at the top of any `<iati-activity>` element which uses the extension, a user should add a `@xmlns:openag` attribute which equals the URL of this extension page.
+
+Furthermore, the `tag` element above should appear at the **end** of an IATI activity file with `openag:tag` as the element name.
+
+Here is a worked example
+
+```xml
+<iati-activities xmlns:openag = "http://openagfunding.readthedocs.io/en/latest/extensions/" version="2.02">
+<iati-activity>
+  <!-- .................. -->
+  <!-- the rest of the    -->
+  <!-- activity: sectors, -->
+  <!-- transactions, etc  -->
+  <!-- .................. -->
+  <openag:tag vocabulary="99" vocabulary-uri="http://aims.fao.org/aos/agrovoc/" code="c_4397">
+      <narrative xml:lang="en">Livestock</narrative>
+  </openag:tag>
+  </iati-activity>
+</iati-activities>
+```
+
+> NB: there can be more than one `<openag:tag>` element per activity.
+
+If you have any questions about implementing this extension, don't hesitate to [get in touch](http://openagfunding.readthedocs.io/en/latest/contact/).
+
+### Using tagged data
+
+If you are building an tool that uses IATI data, consider adding support for the `tag` element. Below are some tips for handling tag data:
+
+**When querying for `tag` data** consider establishing a query that will search for both namespaced, and namespace free, data. This will ensure that your tool is 'future proof' for IATI 2.03, but also can accommodate data that was published before `tag` was adopted in the core standard. 
+
+For example, the xpath below should fetch both extension and core `tag` data:
+
+```xpath
+/iati-activities/iati-activity/openag:tag | /iati-activities/iati-activity/tag
+```
+
+**Be vocabulary aware**. Some tag vocabularies, like AgroVoc, may have a hierarchy to their classifications. You can use this to (a) provide an improved interface for users to select the tags they want to search on; (b) search on all values from a 'child' category when the parent category is selected.
+
+Be careful not to mix information from different vocabularies together when displaying tags to users, unless this is appropriate in your interface.
+
+### History and future: towards inclusion in 2.03
+
+In order to allow for the most useful agricultural investment data, the Open Ag Funding Partnership consulted with the IATI community about ways to include additional classifications against established vocabularies. This led to proposals for an addition of `tag` to the next version of the IATI standard (version 2.03).
+
+The primary need met by the `tag` element is to declare classifications which _aren't_ statistical. For instance, if a donor is sure that their project concerns both irrigation and livestock, but doesn't want to split the budget based on those groups (as they would have to in the [sector](http://iatistandard.org/202/activity-standard/iati-activities/iati-activity/sector/) element).
+
+This addition has been accepted and taken forward by the IATI secretariat for inclusion in the next version. Discussion and subsequent consensus can be found [here](discuss_link).
+
+However, the next new version of IATI might not be released for a while, but users want to get going!  This is where extensions come in. IATI XML based standard allows publishers to declare their own extensions using a [namespace extension](http://iatistandard.org/202/namespaces-extensions/).
+
+

docs/getting_started.md

@@ -5,22 +5,22 @@ Getting started
 There are four simple steps to share your data on agriculture and food security projects in a way that will support:
 
 * Better collaboration between donors;
-* Improved targetting of resources;
+* Improved targeting of resources;
 * Discovery and mapping of local partners;
-* Easier evaluation of interventions. 
+* Easier evaluation of interventions.
 
 Over 2017 you can get support from the Initiative for Open Ag Funding to work through these steps. [Contact us](contact.md) for more information.
 
 ## Step 1: Identify your agriculture and food security projects
 
-Open Ag Funding is about publishing enhanced information on investments in agriculture and food security. 
+Open Ag Funding is about publishing enhanced information on investments in agriculture and food security.
 
 ```eval_rst
 .. doc-tabs::
 
-    .. admonition:: Finding your activities 
+    .. admonition:: Finding your activities
 
-        Search your project or investment database or lists for any activities or investments with a focus on agriculture or food security. 
+        Search your project or investment database or lists for any activities or investments with a focus on agriculture or food security.
 
         If you currently classify your activities using the OECD DAC Sector/Purpose codes, we have prepared a list of relevant codes you may wish to check.
 
@@ -32,7 +32,7 @@ Open Ag Funding is about publishing enhanced information on investments in agric
 
 ```
 
-If you have a large number of agriculture and food security activities, you may wish to pilot the Open Ag Funding framework with a sub-set, focussing on a single country or value-chain. 
+If you have a large number of agriculture and food security activities, you may wish to pilot the Open Ag Funding framework with a sub-set, focussing on a single country or value-chain.
 
 ## Step 2: Map your current data practices & plan for updates
 
@@ -44,14 +44,14 @@ Our [data quality framework](framework.md) may require you to:
 * Check that partners are clearly listed; and
 * Include information on results;
 
-for each of the activities you identified in Step 1. Each item in the quality framework has been designed around the data that is needed to improve support improved coordination and funding impact. 
+for each of the activities you identified in Step 1. Each item in the quality framework has been designed around the data that is needed to improve support improved coordination and funding impact.
 
 Creating improved data will need input from:
 
 * **Programme or investment officers** - who will have the knowledge to provide additional activity information;
 * **Technical staff** - who can adapt databases, or data production workflows, to store and publish enhanced data.
 
-The approach to this step will depend on whether you already publish data using the International Aid Transparency Initiative standard or not. 
+The approach to this step will depend on whether you already publish data using the International Aid Transparency Initiative standard or not.
 
 ```eval_rst
 .. doc-tabs::
@@ -64,35 +64,35 @@ The approach to this step will depend on whether you already publish data using
 
     .. admonition:: New publishers
 
-        You will need to decide on an approach to producing IATI data. This may involve mapping your systems against the wider IATI Standard, as well as against the Open Ag Funding framework. 
+        You will need to decide on an approach to producing IATI data. This may involve mapping your systems against the wider IATI Standard, as well as against the Open Ag Funding framework.
 
-        Publishers generally split between (a) building direct integrations with a project database; (b) exporting data periodically into CSV, and converting the data into the IATI XML format. 
+        Publishers generally split between (a) building direct integrations with a project database; (b) exporting data periodically into CSV, and converting the data into the IATI XML format.
 
 ```
 
-In an **upstream approach** you would modify the main database or system you use to create your IATI data to directly include Open Ag Funding fields. 
+In an **upstream approach** you would modify the main database or system you use to create your IATI data to directly include Open Ag Funding fields.
 
 ```eval_rst
 .. image:: assets/upstream.png
    :width: 456 px
    :height: 236 px
-   :alt: Upstream data production 
+   :alt: Upstream data production
    :align: center
 ```
 
-> We are working with creators of common IATI tools to add support for Open Ag Funding fields to their tools, supporting improved upstream publishing. 
+> We are working with creators of common IATI tools to add support for Open Ag Funding fields to their tools, supporting improved upstream publishing.
 
-In a **downstream approach** you would continue current data production practices, but add in a step that works with the exported data to add extra fields. 
+In a **downstream approach** you would continue current data production practices, but add in a step that works with the exported data to add extra fields.
 
 ```eval_rst
 .. image:: assets/downstream.png
    :width: 698 px
    :height: 211 px
-   :alt: Downstream data production 
+   :alt: Downstream data production
    :align: center
 ```
 
-> We are working to develop simple spreadsheet templates that can be used to create or annotate IATI data with the Open Ag Funding fields. Get in touch if you would like to pilot use of these templates. 
+> We are working to develop simple spreadsheet templates that can be used to create or annotate IATI data with the Open Ag Funding fields. Get in touch if you would like to pilot use of these templates.
 
 ## Step 3: Enhance your data
 
@@ -106,9 +106,9 @@ However, such approaches are not 100% reliable, and how successful they will be
 
 On the other hand, manually updating activity descriptions and classifications may require programme officer time and expertise, and may be more difficult to apply to past activities, rather than future activities.
 
-**(2) Periodic vs ongoing enhancement** 
+**(2) Periodic vs ongoing enhancement**
 
-Providing enhanced data could be part of the everyday business process of the organiastion, or it could be carried out as part of a periodic excercise (e.g. once a quarter) that is designed to not only capture data, but also support in-house knowledge-sharing and collaboration. 
+Providing enhanced data could be part of the everyday business process of the organisation, or it could be carried out as part of a periodic exercise (e.g. once a quarter) that is designed to not only capture data, but also support in-house knowledge-sharing and collaboration.
 
 > The guidance here will be updated after our tool development workshop.
 

docs/index.md

@@ -27,6 +27,7 @@ Contents:
    framework
    identifiers
    codelists
+   extensions
    contact
 
 ```