Profiles documentation

docs/design_principles.md

@@ -13,13 +13,11 @@ The format also specifies information about the _provenance_ of the data, as wel
 
 In order to ensure accessibility, the data must be a machine-readable and -writable format that can also be created, updated and deleted with a basic text editor.
 
-
-
-### Related standards
+## Related standards
 
 During the development of HSDS, we have charted our course in conscious relation to a range of related standards. These include:
 
-#### AIRS Standards
+### AIRS Standards
 
 The [Alliance of Information and Referral Systems](http://airs.org) is an international professional association that provides standards, accreditations and certifications for the information and referral sector. 
 
@@ -36,14 +34,14 @@ As described in the AIRS Standards and Quality Indicators publication, the Resou
 In part through engagement with Open Referral, [AIRS recently adopted an open source license (CC 4.0 BY-SA) for their Style Guide](https://openreferral.org/the-2016-airs-style-guide-newly-open-sourced/).
 
 
-#### schema.org for Civic Services (W3C)
+### schema.org for Civic Services (W3C)
 
 The [Civic Services schema](https://www.w3.org/wiki/WebSchemas/CivicServices) is a W3C-approved vocabulary, originally proposed by the Google.org Social Impact team in 2013, to extend the Schema.org schemas to better support the description of public civic services.
 
 It is a new vocabulary, similar to the European Commission ISA Core Public Service vocabulary. Its purpose is to improve search engines’ understanding of these services. The schema will provide "*enough information to determine the service, the area covered by the service, and relevant information for using the service*."
 
 
-#### National Information Exchange Model (NIEM)
+### National Information Exchange Model (NIEM)
 
 NIEM is the National Information Exchange Model. It is an interagency initiative to create a national-level interoperable information sharing and data exchange. The NIEM project began in 2005 as a joint venture between the U.S. Department of Homeland Security (DHS) and the U.S. Department of Justice (DOJ). The NIEM uses both the Global Justice XML Data Model (GJXDM) reference model and the GJXDM XML-based framework and support infrastructure.
 
@@ -55,23 +53,23 @@ NIEM consists of a  collection of data components organized in multiple kinds of
 The schema for the core components is available from [niem.gov](http://release.niem.gov/niem/niem-core/2.0/niem-core.xsd). Open Referral encourages the establishment of compatibility with NIEM.
 
 
-### Related Taxonomies
+## Related Taxonomies
 
 Open Referral recognizes the existence of a diverse array of taxonomies to describe types of services, organizations, and people for whom services are available. Given that such categories are inherently subjective, whereas Open Referral's format is describing only *factual* data, we do not prescribe a specific taxonomy. In the meantime, we recognize the existence of the following taxonomies, and offer guidance for using them in conjunction with HSDS.
 
 
-#### AIRS/211 Taxonomy
+### AIRS/211 Taxonomy
 
 [The AIRS/211 taxonomy](https://www.airs.org/i4a/pages/index.cfm?pageid=3386) is widely used among certified providers of ‘information and referral’ services, as well as some government agencies. The Taxonomy is a hierarchical system that contains more than 9,000 fully-defined terms that cover the complete range of human services. 
 
 The AIRS/211 taxonomy is the intellectual property of 2-1-1 Los Angeles. Licensees can use the taxonomy with data formatted in HSDS.
 
 
-#### Open Eligibility
+### Open Eligibility
 
 [Open Eligibility](http://openeligibility.org/) is a "*simple way to categorize human services and human situations*." It uses common categories for quickly finding human services for people in need, service providers and navigators. It takes a different approach than the AIRS taxonomy by offering up sets of 'tags' that describe _types of services_ and _types of situations_. Open Referral has included [a fork of Open Eligibility in our Github organization](https://github.com/openreferral/openeligibility).
 
 
-#### National Taxonomy of Exempt Entities (NTEE)
+### National Taxonomy of Exempt Entities (NTEE)
 
 [The NTEE system](http://nccs.urban.org/classification/national-taxonomy-exempt-entities) is used by the IRS and the National Center for Charitable Statistics to classify nonprofit organizations. It is also used by the Foundation Center to classify both grants and grant recipients (typically nonprofits or governments).

docs/hsds/variations_interoperability.md

@@ -1,17 +1,54 @@
-Variations & Interoperability
+Profiles, Variations, and Interoperability
 =============================
 
-Like any standard, HSDS attempts to accomodation a wide range of applications, providing value to each application.
+As an international standard, HSDS provides a common core of defintions and objects for describing health, human, and social services as well as their locations and the organizations that provide them. This allows HSDS to acommodate a wide range of applications and provide value in a variety of use cases.
 
-To this end, certain adaptations of the schema are permitted within the standard, and this results in interoperability considerations that must be considered when making design decisions for a particular system.
+Being an international standard, however, means that the needs of HSDS publishers and users are often significantly variable across varying contexts. In different geographies, sectors, and scenarios of usage, users may need different information about services, locations, and organizations.
 
-## Tables-to-fields Transformation
+To this end, HSDS makes several provisions to ensure that the standard can be effectively adapted for use in a given context. The first of these is the *HSDS Profiles* mechanism, by which people can collaboratively build upon HSDS as a base in ways that further shape the standard for a particular purpose. HSDS also offers flexibility for publishing data using a simplified structure in some cases.
 
-If there is a situation where there is at most a 1:1 relationship in a particular system between items in two tables, where those items would be linked by IDs, then it is permitted within the standard for those tables to be merged. Column names should be retained.
 
-If the system in question is part of a wider ecosystem, then the community around that ecosystem should agree on a common approach to interoperability around HSDS. For example - agreeing on a common set of tables, or agreeing that standard HSDS should be available for interchange purposes.
+## HSDS Profiles
 
-For example, if all ‘service’ entries have at most one fee entry, then you can just add a ‘fee’ column to the ‘service’ table.
+The HSDS Profiles mechanism provides a method of building upon and tailoring the core HSDS Schema in order to adapt it for specific contexts which may require different or additional validation rules.
+
+Profiles may declare new optional or mandatory fields, make existing optional fields mandatory, introduce new validation rules or new structures, or declare new API endpoints in addition to those on the [HSDS API Reference](api_reference).
+
+Conversely, Profiles may also remove or override some parts of the HSDS Schema which are not relevant to them. (This will not prevent a publisher from publishing such excluded data, but it may not be validated by tooling used by that Profile, as it is technically additional data from the Profile's perspective.)
+
+Profiles may also recommend the use of particular value sets (taxonomies, enumerations, etc) to ensure semantic interoperability among datasets that use the Profile.
+
+Profiles are generally developed and maintained by third parties to satisfy particular requirements for their context. These could arise from a community need, legal structures, taxonomy requirements, or other affordances of service provision specific to that context. In general, Profiles should provide robust documentation allowing a publisher or data user to understand its rules and structures both independantly and in comparison to the core HSDS schema.
+
+NB: while Profiles may be used to extend the functionality of HSDS, they should not be used to create modular or re-usable "Extensions". The Profiles mechanism differs from that of an Extensions mechanism in other standards; as such, a given dataset may only implement a *single* Profile.
+
+### Publish data using an existing HSDS Profile
+
+You are encouraged to use existing profiles to publish HSDS data when suitable. This is a very straightforward process.
+
+1. **Ensure that you have implemented the Profile-specific requirements.** You should check the requirements of the Profile that you are publishing against and ensure that your data conforms to these. Do you have all the minumum required fields? Are all of your fields in the correct format?
+2. **Declare that you are using the Profile via your API output.** The [`/` endpoint](../hsds/api_reference.md#endpoint-details) of the HSDS API Reference includes a response key/value pair for `profile`. You should populate this with the URI to the profile you are using. Profile documentation should clearly state this value to avoid confusion – if you are unsure which value to use please get in touch with the implementer of the profile.
 
+Existing Profiles that are likely of interest:
 
+* [UK Profile](uk_compliance)
 
+### Developing a new Profile
+
+If the core HSDS standard or an existing Profile does not adequately meet the needs of your context, you may wish to develop a new Profile to provide the standardization and meaning that you and other publishers in your context will need to produce good quality HSDS data.
+
+Creating a new HSDS Profile is an involved but straightforward process:
+
+1. **Engage and Discuss** with the community about which problems you're trying to solve and how best to address them. This may include people in the [wider Open Referral community](https://forum.openreferral.org/) and other implementors in your context who may want to contribute directly to your profile. Speaking to people who have implemented other HSDS Profiles may help you with thinking through some aspects of Profiles.
+2. **Develop and Document** the Profile. All new Profiles should use the [Example Profile repository](https://github.com/openreferral/hsds_example_profile) as a starting point because it contains all of the tools required to generate your final Profile schemas as well as a basic documentation site. The Example Profile contains technical guidance and examples on creating a profile inside its README file. You may want to expand upon the basic documentation generated by the tools in the repository.
+3. **Share and Support** your new Profile! Make an announcement on the [HSDS forums](https://forum.openreferral.org/) and start producing data conforming to your Profile. If others are using your Profile, you may want to collaborate with them to plan changes to the Profile or answer questions by expanding your documentation.
+
+## Tables-to-fields Transformation
+
+As noted in the introduction to this page, the standard permits certain adaptations of the schema. This makes it easier to publish some datasets which are less complex – but this results in interoperability considerations.
+
+If there is a situation where there is at most a 1:1 relationship in a particular system between items in two tables, where those items would be linked by IDs, then the standard permits that those tables be merged. Column names should be retained, however.
+
+If the system in question is part of a wider ecosystem, then the community around that ecosystem should agree on a common approach to interoperability around HSDS. For example –  agreeing on a common set of tables, or agreeing that standard HSDS should be available for interchange purposes.
+
+For example, if all ‘service’ entries have at most one fee entry, then you can just add a ‘fee’ column to the ‘service’ table.

docs/index.md

@@ -45,11 +45,12 @@ Contents:
    hsds/schema_reference
    hsds/api_reference
    hsds/publication_formats_reference
-   hsds/logical_model
    hsds/variations_interoperability
+   hsds/logical_model
    hsds/uk_compliance
    hsds/changelog
 
+
 .. toctree::
    :maxdepth: 1
    :caption: HSDS Implementation Guidance
@@ -67,7 +68,6 @@ Contents:
    :caption: Open Referral Initiative
 
    initiative/index
-   governance
    design_principles
    faq
    credits