Component library¶
On reviewing a range of policy-related data standards, including those that we maintain and those maintained by others, we identified approximately 60 components that at least two standards have chosen to create or adopt.
Whether or not these are important to a particular standard depends on lots of factors, including but not limited to the maturity of the standard, whether the standard’s adoption is being driven co-operatively or adversarially, political factors and the character of the people and organisations in the domain where the standard operates.
We conducted an exercise with representatives of several standards, asking them to conduct a diamond ranking exercise of the components. Diamond ranking was chosen to allow a ‘fat middle’ while forcing a decision on the highest and lowest priority items. Participants were asked to consider a standard at different levels of maturity, using Charles Handy’s Second Curve model for describing maturity.
The list of components is below.
Components¶
Advocacy Plan¶
Summary¶
Setting out steps to encourage organizations to adopt the standard.
Description¶
An advocacy plan provides the resources and sets out the steps that will be followed to encourage organisations to adopt a standard, as well as key arguments. It should be updated regularly as the standard matures and as the standard starts to have an impact.
Prioritisation Factors¶
Where standards are being developed outside of the organisations that are expected to adopt the standard
If there is a perceived cost to adopting a standard
Deprioritisation Factors¶
Where a standard is emerging from consensus among the organisations that are expected to use it
Blog¶
Summary¶
Sharing stories of successful implementation.
Description¶
A blog that is regularly updated can provide updates to the community, resources for them to refer back to, and act as a ‘shop window’ for the standard, demonstrating that it is maintained and used.
Prioritisation Factors¶
Where a wide audience is sought
Deprioritisation Factors¶
If there isn’t the resource available to make regular updates.
Brand Agreements¶
Summary¶
Setting out who is allowed to use the logo, and how implementers should describe their relationship to the standard.
Description¶
Standards that have developed a brand need to ensure that it is used in a way that benefits the community and the standard. This will likely include guidance as to when the logo can be used, how tools should describe themselves relative to the standard, and ensure that the brand is only used when relevant
Prioritisation Factors¶
When a standard is growing quickly
There is a proliferation of tools and adopters, especially those who might use the name of the standard in their services.
Deprioritisation Factors¶
Where there is a trusted community or less of a strong brand.
Related Components¶
Brand Guidance¶
Summary¶
Describing how to use the logo and how to talk about the standard
Description¶
Brand guidance sets out how to use the name, logo, look-and-feel and other identifying marks and conventions. The guidance helps a standard ensure that it isn’t misrepresented, and that there is a clear distinction between the standard and those using it.
Prioritisation Factors¶
If a standard uses the name of a related concept in its own name
During phases of rapid growth with a proliferation
Deprioritisation Factors¶
If a standard has not developed a strong brand
Case Studies¶
Summary¶
Accessible write-ups exploring adoption and impact through narrative stories for a general audience.
Description¶
Case studies give real-world examples of when use of a standard has enabled a particular impact, while giving space for frank discussion of the challenges faced. This helps to set expectations among potential adopters and encourages those currently going through adoption of a standard to be reassured that encountering challenges isn’t exceptional.
Prioritisation Factors¶
Where a standard is more mature and at least one useful real example exists that can be described
Where a strong advocacy is required to encourage adoption
Where a standard’s value proposition is concerned with impact beyond the use of the data - such as social outcomes
Deprioritisation Factors¶
Where no real stories exist
Where the community around a standard already share details with each other
Related Components¶
Communications Plan¶
Summary¶
Setting out steps to get media coverage of the standard.
Description¶
A communications plan sets out the steps that are planned to encourage media coverage of the standard. Having a plan ensures that media opportunities are sought, and that representatives of the standard are well-equipped when taking advantage of opportunities. It can ensure that the standard is properly represented, setting expectations among potential users and beneficaries.
Prioritisation Factors¶
If a standard is likely to be of interest to either general or specific media outlets
If a standard is intended to have an impact outside of its adopters
Demonstration Applications¶
Summary¶
Showcasing what can be done with data when it is published to a standard
Description¶
Demonstration applications are either real-world or contrived applications using standardised data to illustrate what the data could be used for. They can be used to demonstrate the advantages of using the standard at all, or using particular parts of the stardard.
Prioritisation Factors¶
Where the value proposition of a standard is hard to articulate in words
Deprioritisation Factors¶
Early in a standard’s development, as demonstration applications are likely to be costly to develop
Where the community around a standard are developing applications as part of their adoption of the standard
Discourse Forum¶
Summary¶
An online space for community discussion of the standard, adoption and data use.
Description¶
An online space for community discussion of the standard, adoption and data use. By using a forum instead of other online communications mechanisms, a complete audit trail for decisions can be retained and referred to. Over time, forums can become a valuable resource for implementers, and provide rich content for support articles, FAQs and other resources.
Prioritisation Factors¶
When a standard has multiple stakeholders who don’t meet regularly in person
More mature standards
Deprioritisation Factors¶
When the community around a standard regularly meet in person
Draft Commitments¶
Summary¶
Asking potential adopters to sign-up and give their support to the standard.
Description¶
Draft commitments are templates for adopters to copy or adapt before signing and making public. By providing a draft, a standard can ensure that adopters are aware of what they are expected to commit to at the start of the process, and by providing a path of least resistance to a high bar of adoption, a standard organisation can ensure that there is less risk of implementers crafting their own, lower, commitment to adoption.
Prioritisation Factors¶
If a standard requires a relatively high level of commitment to be useful
If a standard is targetting public sector organisations that are keen to formally launch commitments
If a very early-stage standard requires commitment in principle before development begins
Glossary¶
Summary¶
Providing clear definitions for all the terms of art used in a standard.
Description¶
A glossary provides an authoritative and unambiguous list of the terms and their definitions as used in a standard. The definitions may be different from some of those used by adopters, but ensure clarity when using the standard.
Prioritisation Factors¶
If a standard is to be localised or translated
Deprioritisation Factors¶
If the standard relates to unambiguously defined terms in a sector
Guidance Documentation¶
Summary¶
Non-normative guidance on how to share data using the standard.
Description¶
Standards typically comprise a detailed, technical definition of how to publish data. They are often the product of extensive work and research, and are designed to be reference documentation. However, adoption requires adopters to be guided through the process of adoption - helped to understand how to start, where to focus effort, and how to understand concepts. Guidance documentation takes adopters through the process of using the standard, building on real-world experience.
Prioritisation Factors¶
If the standard is large
If the standard uses a representation of concepts that may be unfamiliar to adopters
If early adopters encountered issues or misunderstandings
Deprioritisation Factors¶
If the standard is small, and implementation guidance can be included in the standard
Icons¶
Summary¶
Common visual elements used across documentation and presentations.
Description¶
Icons help with recall of key concepts, and consistency across a range of assets helps to build trust.
Prioritisation Factors¶
If a standard is being discussed across media (eg in print, online and in person)
If the standard is being translated
If the standard introduces concepts unfamiliar to typical adopters
If the standard is being discussed across policy and technical boundaries
Deprioritisation Factors¶
If the standard does not have a defined visual language
If the standard only uses concepts that will be familiar to adopters
Logo¶
Summary¶
A logo for the standard
Description¶
A logo helps to reinforce the brand of the standard, gives a visual cue for recognition in resources, and can be used (with permission) by adoptors to demonstrate their use of the standard
Prioritisation Factors¶
If the standard will be used by a range of organisations
If the standard is operating in an environment where it needs to be given legitimacy and authority
Deprioritisation Factors¶
If the standard is emerging from a community and is mostly for the use of that community
Principles¶
Summary¶
Setting out high-level goals that adoption of the standard works towards.
Description¶
Principles help to focus work around a standard, provide encouragement for those working for the standard as to the purpose of their effort, and provide a ‘litmus test’ for proposals
Progressive Enhancement Framework¶
Summary¶
Supporting publishers to start with unstructured documents, and move on to provide structured and ultimately linked data.
Publication Levels¶
Summary¶
Separating fields into ‘basic’, ‘intermediate’ and ‘advanced’ so that publishers can focus on a small set first.
Publisher Ranking¶
Summary¶
E.g. an annual report ranking datasets and their publishers based on an agreed methodology.
Recommended Data License¶
Summary¶
E.g. the requirement that publishers should use Creative Commons or Open Database License.
Description¶
A recommended license can help to ensure that adopters give due consideration to licensing, as well as setting a high bar for adopters and encouraging intertia among the community using the standard.
Prioritisation Factors¶
If adopters are unlikely to consider licensing as part of their adoption process
If adopters are likely to have concerns over how their data can be used
Deprioritisation Factors¶
If the data that the standard relates to is already governed by a license restriction
Tutorial Videos¶
Summary¶
Providing on-demand overview of how the use the standard.
Description¶
Videos provide the opportunity to deliver a path through learning materials that are available on-demand.
Prioritisation Factors¶
If resources around the standard are unlikely to change dramatically
If adopters find it hard to learn how to do certain things with the standard on account of resources being spread out
Deprioritisation Factors¶
If the standard and related resources are rapidly evolving
Microblogging¶
Summary¶
Twitter (or similar) For communicating with the public.
Description¶
Public microblogging services such as Twitter, Tumblr and Instagram allow a standard to communicate little and often, and to engage with their communities in a relateable way. Some open communities already have a strong presence on microblogging sites, so the friction for engagement is reduced.
Prioritisation Factors¶
If there is a community of potential adopters who already use a particular microblogging service
Deprioritisation Factors¶
If the time, people or infrastructure required to make regular updates is not available
Website¶
Summary¶
A shop-window on the standard, setting in context of wider goals
Description¶
A standard’s website brings together the various component of a standard, giving a single place where the standard can be explained to different audiences, and will act as a place that adopters go to in order to discover resources.
Prioritisation Factors¶
If there are multiple resources relating to a standard
If a standard is intended to be used by a wider community than those instigating it
Deprioritisation Factors¶
If a standard is intended to only be used for a particular community who are involved in creating it
If a standard is part of a wider operation that has its own web presence
API Specification¶
Summary¶
Describing how data should be accessed interactively.
Description¶
APIs allow developers to access data stored elsewhere without needing to obtain and process the whole data set themselves. This lowers the barriers to creating applications that use the data, and encourages use. An API specification sets out a standard way for API developers to present interfaces to the data, meaning that consuming applications are more portable between publishers and removing the design cost for any adopter wishing to publish via an API
Prioritisation Factors¶
If applications may be portable between data providers using the standard
If an adopter is considering building an API
Deprioritisation Factors¶
Early stage standards
If there is no consideration of APIs
If applications are unlikely to be portable between data providers
Codelists¶
Summary¶
Classifications used in the standard
Description¶
Codelists are lists of terms that are provided as part of a standard in order to ensure that values of fields where there are a limited range of options are properly limited in the data, and that concepts map correctly between datasets. For example, a codelist might specify currency codes, to avoid US Dollars being referred to as “$” in one data set and “USD” in another. Codelists can be open or closed - open codelists allow values to be added, while closed codelists do not permit additions
Prioritisation Factors¶
If there are currencies, languages or other commonly enumerated concepts in the standard
If there are data elements that would be rendered as ‘pick one from the list’ in a form
Contributor Guidelines¶
Summary¶
Describing the practices and workflows for contributing to the standard or associated documentation.
Description¶
Contributor guidelines set out the expectations of external contributions to the standard or the tools that are provided to support adopters. They typically cover licensing, procedure for contributions to be reviewed, acknowledgement, and expectations around process. Contributions may include comments in forum threads or in emails as well as formal written contributions.
Prioritisation Factors¶
If there are individuals or organisations who are keen to contribute directly to the standard or tools
If the standard is starting to draw extensively on the ideas and work of the community to develop
Deprioritisation Factors¶
If the standard is being developed entirely by the organisation that maintains it with little external input
Related Components¶
Developer Guidelines
Developer Guidelines¶
Summary¶
Describing the coding practices and workflows for contributing to the standard or associated tools.
Description¶
Developer guidelines set out the expectactions of external contributions to the standard or the tools that are provided to support adopters. They typically cover licensing, procedure for contributions to be reviewed, expectations around process, and technical expectations such as comments, naming conventions, tests and coding style.
Prioritisation Factors¶
If there are individuals or organisations who are keen to contribute directly to the standard or tools
Related Components¶
Contributors Agreement¶
Summary¶
Used to make sure all contributions to the standard are appropriately licensed, and to manage patent risks.
Conversion Tools¶
Summary¶
Allowing conversion between serialization formats (e.g. CSV -> XML; JSON -> XLS)
Description¶
Data standards often use structured data formats such as JSON or XML to give more flexbility in modelling and to allow validation against schema. Typically, developers prefer to work with structured data formats as they are easier to work with in programs. However, JSON and XML aren’t very human-friendly, and people working with data in many domains prefer to use flat representations of data such as CSV and XLSX spreadsheets, both for publishing and manipulating data. Conversion tools allow conversion between the formats, to allow the standard and developers to retain the benfits of a structured data format and users to continue to be able to engage with the data in a way that they’re comfortable with.
Examples¶
Flatten Tool¶
We maintain Flatten Tool, a Python library and command-line interface for converting data between structured formats like JSON and XML and tabular formats like CSV and XLSX. It can use a standard’s schema to handle data types correctly, to produce human-readable column headings, and to structure tabular data helpfully.
Prioritisation Factors¶
If the standard uses a structured data format, while data publishers and/or users prefer flat representations.
Deprioritisation Factors¶
If the standard uses a data format that is the same as both publishers and users prefer to use
Email List¶
Summary¶
Used to discuss the standard, or announce standard updates.
Description¶
Email lists are a widely-accessible and low-cost way for a group to hold discussions, and many email list providers offer a public archive service so that accountability is maintained. Standards often have a discussion list and a separate announcement list, so that members can choose how involved they want to be. The asynchronous nature of email lists allows users to be involved as regularly or infrequently as they prefer. However, some users are reticent to post to public email lists for fear of appearing foolish or having their words during their learning being recorded.
Prioritisation Factors¶
In the early stages of a standard
If a public archive of discussions is important
If key people in the development of the standard are comfortable with public email lists
Deprioritisation Factors¶
If there is reticence among users about public email lists
Data Aggregator¶
Summary¶
Providing access to all the data shared using the standard.
Description¶
Many standards consider one of the best arguments for standardisation is being able to give examples of applications that become possible when the entire data set can be taken as a whole. A data aggregator brings together some or all of the data being published to the standard and enables users to obtain it as a single data set, removing the first barrier to application development on top of the data set, and encouraging experimentation.
Prioritisation Factors¶
If enough sources of standardised data exist to be usefully aggregated
If having access to the whole data set is meaningful
Deprioritisation Factors¶
If the data cannot meaningfully be considered as a whole
If there are few data sources available, or their use of the standard is divergent enough as to make the data incomparable
Example Data¶
Summary¶
Auto-generated and manually created examples used in tutorials, and for testing the standard.
Description¶
Adopters of the standard and users of the data are often helped by seeing examples of what the data could look like. Example data can often give hints that might be missed by reading documentation, and can be used to set expectations of what data should look like.
Prioritisation Factors¶
If the standard is large or complicated
If adopters or users are often misunderstanding the requirements of the standard or strugging to ‘get it’
Deprioritisation Factors¶
If the standard is intentionally loose
If the standard is rapidly changing
If the standard does not have schema or a field model
FAQs¶
Summary¶
Addressing frequently asked questions from publishers and users.
Description¶
FAQs cover common issues and questions that are asked, and can be used to shape implementers’ thinking very early in their process, addressing misconceptions before too much work happens. They can also be a useful reference resource - common solutions to regular issues can be recorded in a single place.
Prioritisation Factors¶
If a standard helpdesk has sufficient traffic to be able to identify common issues
Deprioritisation Factors¶
If a standard wants to ensure that they are in contact with all implementers from an early stage
Field-level Mapping Template¶
Summary¶
Used when preparing to publish data to cross-walk from existing systems.
Description¶
Field-level mapping is a crucial stage in preparing to publish existing data to a standard. A template gives some structure to the activity, can be shared between colleagues, and gives an opportunity for a standard to provide helpful advice in context.
Prioritisation Factors¶
If publishers are extracting data from existing systems to publish using the standard
Getting Started Documentation¶
Summary¶
User-friendly and filled with examples.
Description¶
The normative documentation for standards is technical, prescise, authoratitive and comprehensive. While this is useful for a reference, the process of learning about a new standard is helped by the same kind of learning resources as any other learning process, including worked examples, guided learning through the standard, and practice materials.
Prioritisation Factors¶
If people who weren’t involved in designing the standard are involved in implementation
Issue Tracker¶
Summary¶
Providing clear public trail for all discussions about changes to the standard.
Description¶
Discussions around changes to data standards and suggestions for improvements often happen in different places - in technical and policy forums, in person, in private chats and elsewhere. An issue tracker provides a single place where such discussions are recorded, and discussion can advance. Later, an issue tracker allows the community to see the rationale behind a decision, allowing discussion to pick up if a change is desired.
Prioritisation Factors¶
If discussions around the standard are happening in multiple places
Helpdesk Email Address¶
Summary¶
Providing a place to ask implementation questions.
Description¶
A helpdesk email address provides an accessible, on-demand, asynchronous way for questions about the standard to be answered. They may go to a single person, or a team may share an inbox and prioritise work accordingly.
Prioritisation Factors¶
If there are implementers who aren’t already part of the network creating the standard
Helpdesk Phone Number¶
Summary¶
Direct access to talk to someone about adopting the standard.
Description¶
A direct phone number provides rapid access to implementation support, and can help to build relationships between implementers and those maintaining the standard. It can encourage little-and-often access to support, which may help implementers avoid early misunderstandings. However, many implementation issues require sharing of data or in-depth investigation, which can’t be easily carried out over the phone.
Prioritisation Factors¶
If implementation questions can easily be answered over the phone
Deprioritisation Factors¶
If there aren’t sufficient staff or volunteers to offer the level of cover expected
Implementation Plan Template¶
Summary¶
To be filled in by someone planning to adopt the standard.
Description¶
The Implementation Plan Template provides an overview of the planning required for an implementation - the stages to go through, the factors to consider, the preparation required, and the path to implementation. Having a plan provides confidence of success for implementers and stakeholders, and helps the standard to provide support proactively instead of just responding to questions.
Prioritisation Factors¶
If implementing the standard requires multiple stakeholders
Maintenance Handbook¶
Summary¶
For the team maintaining and updating the standard.
Description¶
The maintenance handbook provides a place for the team developing and maintaining the standard itself, to record decisions and best practices, to store solutions to common problems, and to hand over as people leave and join the team. It can be used to encourage wider contribution to the maintenance, by ensuring that even occasional contributors understand the practices of the standard.
Examples¶
Prioritisation Factors¶
If there are multiple people developing the standard
Online Validator¶
Summary¶
Providing a report on technical validity of data against the schema.
Description¶
Part of a standard is often schema, and reporting on technical validity against the schema is a way of programmatically checking that the data conforms to the schema and can be used by other tools that expect data to conform to the schema. By providing validation as an online service, implementers can validate their data without
Quality Tool¶
Summary¶
Providing feedback on the content of datasets, based on a set of data quality rules.
Recommended Fields¶
Summary¶
A list of fields that publishers are encouraged (but not required) to provide
Reference Documentation¶
Summary¶
Normative. Describing all the elements of the standard, and used as the basis for any judging correct or incorrect implementations.
Reference Lists¶
Summary¶
Lookup lists for key concepts (e.g. organization registers).
Registry Of Datasets¶
Summary¶
Providing links to all known data that follows the standard.
Required Fields¶
Summary¶
A list of fields that MUST be provided.
Research Report¶
Summary¶
Independent evidence concerning data publication and use.
Rules For Additional Checks¶
Summary¶
Machine and human-readable rules used to check data quality.
Schema¶
Summary¶
The technical description of how data should be structured.
Self-Certification¶
Summary¶
So that standard users can describe the coverage and comprehensiveness of their data.
Slack¶
Summary¶
For chat-type conversations with the community about development, adoption and use of the standard.
Specification¶
Summary¶
Comprising of the schema, codelists and normative documentation.
Spreadsheet Template¶
Summary¶
An editorialised template that can be filled in to provide data that meets the standard (Excel / AirTable etc.)
Training Resources¶
Summary¶
Used in online and offline training workshops to introduce the standard.
Unit Tests¶
Summary¶
Automatically run whenever the specification, documentation or examples are updated.
Use Cases¶
Summary¶
A description of the ways in which data from the standard could be used.
Use-Case Mapping¶
Summary¶
A cross-walk between outcomes from data use, and the fields or data requirements to enable them.
User Tutorials¶
Summary¶
How to guidance on making use of published data
Extensions Registry¶
Summary¶
A list of known extensions to the standard
Extensions Mechanism¶
Summary¶
A mechanism for having optional new codelists, schema and documentation added to the standard.
Workshops¶
Summary¶
A mechanism for having optional new codelists, schema and documentation added to the standard.
Governance Body¶
Summary¶
A mechanism for having optional new codelists, schema and documentation added to the standard.
Dashboard (data publication statistics)¶
Summary¶
A single location for accessing reports on the number of publishers, status of current publication, validation errors, coverage of key fields, use of extensions and other key facts.
Description¶
A dashboard helps to answer questions like:
Who is publishing using the standard?
How many publishers are using version 1.0 or 1.1?
How many publishers are using this specific field?
What values are used in this specific field?
Which codelists are publishers using?
Which are the most common validation errors?
If we deprecate a particular field, which publishers will be affected?
Examples¶
The IATI Dashboard fetches changed data on a nightly basis (based on data in the IATI registry) and builds a collection of statistical reports, as well as maintaining historical data to show change over time.
Related Components¶
Contact Relationship Management (CRM)¶
Summary¶
A Contact Relationship Management (CRM) system can be used to track the different actors engaging with a standard, including implementers, users and support providers.
Description¶
A CRM may be used for:
Outreach and engagement - identifying potential standard adopters, users and champions, and keeping track of communication and engagement with them;
Knowledge management - keeping track of communication with particular standard adopters; making sure technical support and policy engagement is joined up; and providing access to consistent technical support answers;
Time tracking - to supported charging by helpdesk consultants, or to allow reporting on which adopters require the greatest investment of time and support;
Reporting - to track progress towards key adoption metrics, and to measure key performance indicators for a helpdesk;
Useful CRM features for supporting a standard include:
Contact profiles
Task tracking
Agile board
E-mail integration or e-mail helpdesk
Knowledge base
Examples¶
The Open Contracting Data Standard makes use of a customised instance of RedmineUp, using the helpdesk plugin to create new contacts for each incoming e-mail, and using time-tracking against tickets for regular reporting.
360Giving uses Salesforce to track the progress of publishers.
Prioritisation Factors¶
The standard needs to report on levels of adoption
The standard is providing a helpdesk to adopters
There are multiple teams engaging with each adopters
Deprioritisation Factors¶
The standard is early stage
There is no central support offer