Project Documentation
The Open Referral Initiative is developing common formats and open platforms for the sharing of community resource directory data — i.e., information about the health, human and social services that are available to people seeking help.
This documentation describes the Open Referral Initiative’s strategic framework. It is a living document! Please ask questions and offer suggestions by leaving a comment.
Vision
The vision of Open Referral is a world in which everyone has access to — and the ability to effectively use — information about resources available in their community.
Mission
The mission of Open Referral is to establish capacities to produce and share resource directory information as a public good. We pursue this mission in three ways:
Develop data exchange standards that enable interoperability across various technologies and institutional contexts.
Support the sharing of resource data among diverse systems – including interoperable platform technologies, data partnerships, and open data business models – that improve the accessibility, reliability, and sustainability of resource data in pilot projects.
Foster a community of practice dedicated to the provision of community resource data as a public good.
Values and Principles
The Open Referral Initiative is guided by a set of values (the good things we aim to achieve) and principles (the ways we work together). Taken as a whole, these establish a set of boundaries within which our community can thrive – guiding our analysis, decision-making, evaluation, and so on. These values and principles have been articulated through years of dialogue among stakeholders across our network. We welcome any interested participant into our network under the assumption that they abide by these statements.
Values: what we work for
Accessibility: we help stakeholders ensure that resource directory data is as accessible as possible, through any information channel that might meet the needs of our community’s members.
Interoperability: we seek to ensure that resource directory data can be used in any technology that might usefully serve help-seekers, help providers, analysts, and any civic leaders.
Reliability: we promote systems that are reliable – in accuracy of information, quality of service, and trustworthiness of relationships.
Sustainability: we seek to ensure that our stakeholders’ operations can be sustained through fair and equitable arrangements.
Principles: how we work together
The Open Referral community is open to all who wish to work towards a future of open, interoperable, reliable, and sustainable community resource directory data — and who abide by the following principles:
Open source. Open Referral works in the open. We promote open data, we develop open source technology, and we share knowledge about all of the above. We specify open source licenses (such as Creative Commons By-Attribution Share-Alike) for code, content, and collateral produced through our projects. We also strive to be open in our processes — including contracting and fundraising — to whatever degree is possible. Business intelligence specific to our contracted partners may remain private or clearly attributed. That said, we publicly document our decision-making processes and outputs to whatever degree is appropriate.
Users’ prerogatives. Open Referral prioritizes the interests of people in need, and the people who serve them. We focus on the interests of people in need — and the people who help them — as the primary lens through which we design sustainable business models. Throughout our pilot projects, we engage with such stakeholders to ensure that their priorities and realities are taken into account. Here is our summary of our primary user types and their respective needs: Personas and User Stories.
Test assumptions. Open Referral evolves by learning, doing, and iterating. This is a complex, long-term undertaking that we tackle step-by-step. We will keep a running list of possible actions, and regularly revisit this list at agreed-upon intervals to assess progress, calibrate priorities, and make specific commitments for the coming cycle(s). In this manner, we aim to deliver something of tangible value at regular increments, rather than trying to build everything in one fell swoop. We make our assumptions explicit in order to test them. Ultimately, our mission is to produce learning, even more than code and data.
Be kind. Open Referral premises all relationships upon dignity and mutual respect. The application of this principle ranges from our commonplace expectations of kindness and good faith, all the way to our commitment to shared agency in decision-making. If someone draws attention to a problem, they should also be ready to help identify and effect a solution. If trust is violated and not repaired, we reserve the right to exclude parties from the forum and associated activities.
Assumptions and Hypothesis
Assumptions
These are a set of stated assumptions that gird this initiative. We will test them.
It is possible to establish interoperability between AIRS / 2-1-1 standards (both schema and taxonomy) and new standards such as the W3C civic services schema.
Adoption of open data standards is a necessary step towards making community resource directory data freely accessible and reliable for the many ways in which it’s needed.
Data standards can help spur innovation of new tools, partnership strategies and business models – lowering the cost of development, promoting sustainability, and bolstering a community of practice that builds capacity and generates knowledge throughout the field.
The production of open community resource directory data can be made sustainable through equitable business models that serve the public good.
Communities already have most, if not all, of the resources they need to sustainably produce reliable open data. However, these resources are currently trapped in redundant, competing data silos; it will require both technological development and partnership development to break down those silos.
The cost of maintaining up-to-date resource data can be lowered by opening systems to receive input from users.
The cost of data maintenance will not drop to zero even in standardized open infrastructural systems; some designated steward(s) of the data will remain necessary to ensure reliability and accountability.
Local stakeholders can play a leading role in researching, proposing, and implementing plans to achieve that sustainability.
Hypotheses:
We can develop a web-based exchange format that is broadly applicable (covers most of the critical information in most of the cases), usable by various stakeholders in various contexts (reasonable to adopt), and interoperable with other standards (such as the AIRS XSD, W3C civic services schema, HL7’s FHIR, etc). We have validated this hypothesis :)
If we adopt a standard format for describing a common core set of directory data, the cost of developing and re-deploying new tools and websites will decrease, while the number and quality of such tools and sites will increase. We have validated this hypothesis :)
“Open data systems” can increase distributed usage, which will yield an increase in user-submitted feedback on data quality, which will then yield a decrease in the cost of maintaining data quality. Our pilot projects are working to validate this hypothesis.
When an information system evolves into the ‘open data hub’ of a referral ecosystem, it can exponentially increase the distributed use of its resource data, while increasing its business opportunities to generate revenue for guaranteed levels of service and value-adding features associated with this data. For instance, metadata about the distributed use of resource data can be collected, analyzed and made available as business intelligence in exchange for revenue from funders, researchers, and governments. Our pilot projects are working to validate this hypothesis.
Organizations that maintain information about overlapping sets of services can cooperate by exchanging data and coordinating activities in mutually-beneficial ways, decreasing the costs of data maintenance and increasing the quality of available data. Our pilot projects are working to validate this hypothesis.
Background
Open Referral was initiated by the DC Open211 project, which is working to consolidate several siloed community resource directories into a shared, open platform.
The launch of Open Referral was co-sponsored by Code for America (CfA).
Open Referral developed our data specifications in partnership with the Alliance of Information and Referral Systems, along with dozens of other institutions.
Additional background is available on our website.
Types of use and user personas
Open Referral recognizes a small set of ways that resource directory data is used – each such type of use is associated with diverse types of users. These constitute our primary groups of stakeholders – and this array of perspectives establishes the critical framework through which we conceive, design, and evaluate the products created by our initiative.
Seeking Help
e.g., help-seeker, clients, patients, end-users, consumers
Providing help
e.g., referrers, service providers, case managers, social workers, librarians, call operators, etc
Administering data
e.g., resource specialist, database manager, IT staff, the intern who updates an Excel spreadsheet, etc
Research and Analysis
e.g., researcher, analyst, wonk, community planner, community leader, decision-maker, etc
The following sections include our User Personas for each of these types of use. A user persona describes a broad category that encompasses many possible ‘subtypes’ of users. The persona articulates general attributes shared by all, including: relevant personal context, what information is needed and why, points of pain in the current system, and description of their behavior. A user story describes a desired action and its resulting benefit.
Seeking Help (i.e. help-seeker, clients, patients, end-users, consumers)
Help-seekers (i.e. patients, clients, consumers, victims, survivors, etc.) have some pressing need (or more likely, multiple needs) which might be addressed by services in their community. This category may include caregivers or any person who is informally seeking help on another’s behalf.
Help-seekers need accurate, relevant, and easily understandable information about services which they can access and for which they are eligible. However, help-seekers may not be fully capable of articulating the addressable aspect of their needs. They may have limited media literacy, and limited access to technology. They may not know about the existence of relevant services, let alone the ‘correct’ language to describe those services. They may have difficulty processing and/or trusting information. They may not be able to articulate their needs and may not feel safe. They may struggle with anticipated or actual stigmatization for seeking help. Heightened emotional reactions, illness or injury may diminish their capacity for uncertainty and decision-making. Incorrect information can cost help-seekers time, money, or even conceivably lives.
Help-seekers might currently look for help by searching the web, or turning to a trusted community anchor like a library, school, or religious institution. They might interface with a service provider (“referrer”) who might help identify addressable needs (through some screening process) and provide them with actionable information about services.
As a help-seeker, I want to…
know that technology is supporting humans who are providing help, rather than replacing them, so that I can still talk to a person in this process.
have fewer places to contact and so that the experience of seeking help is not traumatic.
have privacy so that friends and relatives don’t find out about my problems.
receive simple, step-by-step instructions because when I’m stressed out I give up more readily.
quickly find reliable and easy-to-understand information about services through Google and other search engines
get consistent information among agencies so that I can trust it (or I won’t use it).
Providing help (i.e. referrer, service providers)
The key point in a referral process is often a person who engages directly with a help-seeker (often in person) and helps them find information about relevant and accessible services. A ‘referrer’ is usually (but not always) a professional or a volunteer who is working for some organization that itself provides a service to its community. They are likely to be poorly paid and poorly trained. Referrers are typically the primary users of resource directory information systems.
Referrers want to trust the information they provide to help-seekers — trust regarding a) the information’s accuracy, b) the service’s relevance (is the client eligible), and c) the quality of the service. They may rely as much if not more on ‘tacit’ knowledge about services, drawn from their own experience, rather than an information system. They may use printed resources. Or they may use Google or other web searches. They may need to be able to deliver information in multiple languages.
Referrers often interact with help-seekers in the course of some kind of structured workflow. They likely conduct a screening process which identifies important attributes of the help-seeker’s situation. Referrers then match what information they have about a help-seeker to information about accessible and relevant services. Referrers are not necessarily the penultimate stop in the referrals process. A thorough referrer will call the organization before handing off the referral, and may also call to follow up.
As a referrer (aka service provider, etc), I want to…
Specify the type of help needed in a detailed way so that help-seekers receive the specific type of help they need.
To describe client’s needs just once, so that I don’t waste time.
Track success so that over time our clients’ lives will improve.
Track my cases along with where they received service so that I can respond quickly to funding researchers from the city.
To know that a change in my process will help me deliver service better than I currently do.
Data Administration (i.e. resource data specialist, IT staff)
Data administration is typically an “internally facing” role, involving someone who has responsibility of some kind for an information system. This refers to the work done by system administrators, data producers, vendors, volunteer civic technologists, people who compile directories of all kinds.
Data admins are responsible for information production and maintenance — such as updating records, maintaining naming conventions, running reports, designing mechanisms for retrieval and delivery, etc. They may be responsible for reporting directly to funders and government agencies. These responsibilities are sometimes shared among several roles in an organization.
Updating data may entail email updates, verbal updates (often over the phone), screen scrape, unvalidated free-form notes, vetting user-submitted input.
Administering data entails some level of technical skill, though these skills may have been gained in an ad hoc way, as a data administrator’s job may not technically be in “IT.” Thus, the data admin’s ability to use a system may depend to a great extent on the available documentation and training. They may be working with ambiguous instructions, with important context that might not be explicitly conveyed.
Data admin may be trying to share the burden of data maintenance with low-level, high-turnover human resources – which means they need simple instructions that are easy to convey to newcomers and yield predictable output.
Generally, they want more people to be able to make better use of the data that they are administering.
As a data administrator, I want:
a clear repeatable process flow, so that I can help people help me
a simple and easy to use interface, so that I can update data quickly and efficiently
an automatic and continuous data feed, so that I can speed data updates and validation
to receive feedback from users, so we can constantly improve the quality of information
to track who did what updates so that we can quickly assess the freshness and accuracy of the data
Research (i.e. analyst or researcher)
Researcher: This type of user includes anyone who wants to use service directory data in synthesis with other kinds of data for the purpose of understanding community health, predicting future needs, identifying funding gaps, and other kinds of analysis. Such a role is often played by funders, policymakers, planners, or community leaders.
Researchers are seeking accountability for the performance of the health, human, and social service system overall. They want their work to make this data useful for system-level decision-making.
They currently get data “wherever they can find it,” often having to extract from Excel spreadsheets or other formats that aren’t designed to be used in this way.
Researchers are often looking to understand the effectiveness of programs, which aren’t necessarily specific services but rather may include a set of services that are bundled through a particular funding stream and around a common mission.
Researchers need reliably-structured data from across institutional and jurisdictional boundaries that can be readily ‘mashed up’ with other kinds of data (census, funding, etc).
As a researcher, I want to…
See meaningful context for service information so that I can perform population-level analysis.
Know who is responsible for a service so that when it’s working well (or isn’t) we know who to contact to learn more… and replicate those successes or propose improvements.
Download data in raw formats over a specific time period so I can analyze program utilization and outcomes.
Governance and Participation
Open Referral is an open community of practice – anyone who shares our vision and values is welcome. Our network (which includes human service referral providers, government officials, academics, vendors, community leaders, etc) is primarily assembled in our Community Forum. We also have a Slack team, and discuss technical issues in Github.
Though we are an international initiative, our subject is primarily local and therefore much of the work in our initiative is done locally. This means our decision-making processes are distributed – from global (as an open community of practice, developing a common standard, collateral materials, open source tools, etc) to local (as a set of place-based pilot projects led by stakeholders in a given geographical region) and sectoral (with projects in specific subdomains like legal aid, etc). We operate iteratively, with regular opportunities to reflect, change, and grow.
Core team facilitates alignment and supports activities across the Open Referral network.
At a ‘global’ level, Open Referral consists of technical and institutional leadership. Core team members a) set the agenda for public discussions; b) oversee accountable administration of any grant funding or other resources in the Open Referral Initiative’s control; and c) make decisions in any instances in which the community cannot reach rough consensus.
Workgroups of designated leads who advise on design, implementation and governance.
Workgroups may be formed by any set of members to operate in accordance with the Initiative’s values and principles, and are empowered to make proposals subject to rough consensus of the Initiative’s community. Workgroups can consist of at least two community members who agree to collaborate on a stated objective such as the development of Open Referral’s data specifications, implementation guidance, tooling, the governance model for Open Referral itself, etc. Workgroups should include at least one Subject Matter Expert to represent users’ needs, and at least one Lead Facilitator to be accountable for coordinating activities including setting agendas and taking detailed notes – all of which is expected to be reported on in our regular Assemblies and/or shared in Open Referral’s community forum with appropriate notice. Additional Workgroup members can be nominated by the community (including self-nominations by community members) and/or invited by core team members.
Workgroups should demonstrate that aspects of any proposal put forth are directly informed by perspectives and interests expressed by representatives of Open Referral’s primary beneficiary groups – and are expected to field and respond accordingly to any such feedback received externally. In instances where rough consensus cannot be attained, even after parties have put forth and evaluated alternative proposals and feedback from lead stakeholders of pilot projects has been solicited, Core Team leads reserve the right to make decisions (and will appropriately document the rationale for decisions and ensure the result of those decisions are subject to subsequent evaluation and possible revision).
Technical Standups and Community Assemblies – In semi-regular meetings open to all members of the community, we facilitate alignment around the mission of the Initiative.
Leadership and technical implementers convene monthly at brief Technical Standups. At semi-regular Assemblies, all are welcome to discuss issues of interest to the commnunity as a whole. Anyone can join the Forum and request to be added to the calendar for these meetings.
Summits We also host quasi-annual Summits (longer open meetings) in which we convene share, learn, deliberate, and generate proposals. Summits are not decision-making events, but are critical opportunities for sharing knowledge, building relationships, and setting the agenda for future development. These events can generate and prioritize “user stories,” feature backlogs, and possible courses of action to meet the needs expressed by those user stories. (See this report back from the inaugural workshop.)
Local pilots implementing data exchanges, evaluating specs, planning for the future.
Open Referral focuses much of our work in local pilot projects. In pilots, project stakeholders collaborate to promote access to up-to-date resource directory data in their communities, by using Open Referral’s data exchange specifications to share resource directory data among existing and/or emerging systems. In return, stakeholders can receive facilitation, technical solutions and support, and other kinds of capacity-building when possible, helpful, and appropriate. Feedback from such stakeholders shapes the ongoing evolution of Open Referral.
Pilot projects’ objectives include short-term demonstrations of the value of open and interoperable resource directory systems, and strategic plans for long-term sustainability of such systems. Local pilot projects should consist of teams, anchored around lead stakeholders (see below) who will be represented by some leadership structure (a ‘table’ or ‘committee,’ etc) – and ideally supported by some core-coordinating capacity of their own (sometimes called a ‘backbone’ as in the Collective Impact coalition model). Pilot projects might also be supported by partners, i.e., organizations that provide material support, technical assistance and/or other in-kind resources – such as philanthropic funders, contracting agencies, civic technology networks, software vendors, etc., who can help with implementation, if not decision-making.
Stakeholders include any intended beneficiary of Open Referral’s work, as described by our User Personas documentation. (These broad types of beneficiary user groups consist of: help-seekers, help providers, data administrators, and data analysts.)
Practically, most stakeholder groups are represented in Open Referral by the organizations that serve them (service/referral providers, technology vendors).
Lead stakeholders are voluntary representatives of specific stakeholder groups who commit to the design, implementation, and/or evaluation of Open Referral’s protocols and products through resource data exchanges and associated projects – typically in the context of pilot projects.
Lead stakeholders’ input is prioritized through all phases of Open Referral’s activities; in instances when Open Referral needs more insight to make a decision, we engage with lead stakeholders to solicit relevant feedback from their stakeholder communities.
Get Involved
You can contribute to the development of these protocols in several ways:
Add annotations to this documentation site using hypothes.is - hypothes.is is an annotation service that is embedded in this site. (See the buttons in the top-right of this page.) Just highlight any text, and then use the pop-up box to add your comments. You will need to sign-up for a free account with hypothes.is.
Add a new issue or engage with an existing issue on GitHub. We use this issue tracker to schedule all formal updates to the specification. Anyone can view and search the issues already raised. You will need to sign up for a free GitHub account to comment or create issues.
Join our community forum where discussions around the specification are encouraged.
Request office hours. Upon request, the Open Referral leadership will convene to discuss any issues that participants bring up. Email info@openreferral.org to request an invite.
Roadmap
You can find upcoming milestones and issues on our development roadmap through the specification’s issue tracker