A Single Source of Truth (SSOT) for the IATI Standard

[Ben Webb]

Over the past month I've been working on consolidating all the source information that comprises the IATI Standard into one place - the Single Source of Truth (SSOT). 

We want to be in a position whereby we can alter our key information (schema, guidance, codelists, etc) in one place, and know that the changes will be reflected wherever they are used/displayed/consumed as they are derived from the one master copy. We have been doing some of this piecemeal over the last couple of years, but we are now establishing a new process to do this.

For most people, we anticipate that this will be an invisible, backend system, that they need never know or care about. However, developers may be interested and should also be able to take advantage of our set up.

We have chosen GitHub as a platform on which to host the SSOT (located in the IATI/IATI-Standard-SSOT repository, and its submodules[1]). For a fuller description of the setup see https://github.com/IATI/IATI-Standard-SSOT/blob/master/meta-docs/index.rst

What's the advantage?

It will be much easier to interact with the IATI Standard, and see how all the components of the IATI standard come together. It also allows us to bundle up all the documentation related to each version of the standard. Derived works should be easy for us to generate, for example, the human readable documentation at iatistandard.org will be generated from these GitHub repositories. A development version of what this may look like can be seen at http://dev.iatistandard.org/

What's the current status?

This is currently a development prototype, although much of the technical work has been completed. Much of the work left is around determining human processes for updating, and suggesting updates. We think this is the way forward, but we need to share it more widely to see what you think!

We hope to test the human processes involved in maintaining the SSOT, and building the derived works (e.g the website!) alongside the change process leading to the  1.04 release of the standard.

What will this change mean for me?

If you simply want the text documentation or schema downloads, these will be exactly the same as before. However, if you want to fetch all machine readable information for a given version of the standard, you will be able to leverage the power of GitHub.

When can I start using this?

We're looking for some early adopters, to prod, poke and test it to its limits. If you would like to be involved then please let us know at co...@iatistandard.org

However, if stability is your thing, we encourage you to wait until slightly before the 1.04 release, when we hope to declare the SSOT stable. We will of course update people via this list or you could follow our progress via the repository.

Thanks,

Ben

[1] https://github.com/IATI/IATI-Standard-SSOT has four submodules:

    https://github.com/IATI/IATI-Extra-Documentation

    https://github.com/IATI/IATI-Schemas

    https://github.com/IATI/IATI-Codelists

    https://github.com/IATI/IATI-Rulesets

[Rolf Kleef]

Hi Ben, all,

I've just created another pull request for a minor fix in the IATI SSOT
(https://github.com/IATI/IATI-Schemas/pulls)

- I'm not sure if such pull requests are a good way of working (it's at
least fun to quickly make a fix and send it upstream).

- I saw for instance on
http://iatistandard.org/activities-standard/participating-org/ that
there's info on compliance testing for that field, but that information
is not in the schema file. Should it be added to the documentation in
the schema, should it be generated from "rulesets", or do you envision
another way to tie this together?

- There is a codelist for Organisation id's that do not follow the
country-registrar-registration format
(http://iatistandard.org/codelists/organisation/) but this list is not
in the Codelist repository. Should it be?

- The list is last updated in March 2012. In the meantime, Hivos has for
instance decided to pick NL-2 as their organisation id. Should that be
added to this list, or should Hivos be asked to switch to a NL-KVK-...
format?

- Should this conversation be on this IATI-technical list? :-)

--Rolf.

On 29/11/13 12:05, Ben Webb wrote:
> Over the past month I've been working on consolidating all the source
> information that comprises the IATI Standard into one place - the Single
> Source of Truth (SSOT).
>
> We want to be in a position whereby we can alter our key information
> (schema, guidance, codelists, etc) in one place, and know that the
> changes will be reflected wherever they are used/displayed/consumed as
> they are derived from the one master copy. We have been doing some of
> this piecemeal over the last couple of years, but we are now
> establishing a new process to do this.
>
> For most people, we anticipate that this will be an invisible, backend
> system, that they need never know or care about. However, developers may
> be interested and should also be able to take advantage of our set up.
>
> We have chosen GitHub as a platform on which to host the SSOT (located
> in the IATI/IATI-Standard-SSOT repository, and its submodules[1]). For a
> fuller description of the setup see
> https://github.com/IATI/IATI-Standard-SSOT/blob/master/meta-docs/index.rst
>

> *What's the advantage?*

> It will be much easier to interact with the IATI Standard, and see how
> all the components of the IATI standard come together. It also allows us
> to bundle up all the documentation related to each version of the
> standard. Derived works should be easy for us to generate, for example,
> the human readable documentation at iatistandard.org will be generated
> from these GitHub repositories. A development version of what this may
> look like can be seen at http://dev.iatistandard.org/
>

> *What's the current status?*

> This is currently a development prototype, although much of the
> technical work has been completed. Much of the work left is around
> determining human processes for updating, and suggesting updates. We
> think this is the way forward, but we need to share it more widely to
> see what you think!
>
> We hope to test the human processes involved in maintaining the SSOT,
> and building the derived works (e.g the website!) alongside the change
> process leading to the 1.04 release of the standard.
>

> *What will this change mean for me?*

> If you simply want the text documentation or schema downloads, these
> will be exactly the same as before. However, if you want to fetch all
> machine readable information for a given version of the standard, you
> will be able to leverage the power of GitHub.
>

> *When can I start using this?*

> We're looking for some early adopters, to prod, poke and test it to its
> limits. If you would like to be involved then please let us know at
> co...@iatistandard.org
>
> However, if stability is your thing, we encourage you to wait until
> slightly before the 1.04 release, when we hope to declare the SSOT
> stable. We will of course update people via this list or you could
> follow our progress via the repository.
>
> Thanks,
> Ben
>
> [1] https://github.com/IATI/IATI-Standard-SSOT has four submodules:
> https://github.com/IATI/IATI-Extra-Documentation
> https://github.com/IATI/IATI-Schemas
> https://github.com/IATI/IATI-Codelists
> https://github.com/IATI/IATI-Rulesets
>

> --
> You received this message because you are subscribed to the
> "IATI Technical" discussion list. Find out more at
> http://wiki.iatistandard.org/community/mailing_list
>
> To post to this group, send email to iati-te...@googlegroups.com
>
> To unsubscribe from this group, send email to
> iati-technica...@googlegroups.com
>
> For more options, including the option to switch to a digest
> subscription, visit this group at
> http://groups.google.com/group/iati-technical
>
> Tickets for the IATI technical secretariat can be posted to
> http://support.iatistandard.org
> ---
> You received this message because you are subscribed to the Google
> Groups "IATI Technical Advisory Group" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to iati-technica...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.

--
Rolf Kleef Open for Change, network for open development
ro...@openforchange.info +31617232772 @rolfkleef www.openforchange.info

Internet trailblazer. Weaving the web to help humanity. Implementing
open data, open organisations and online collaboration in civil society.