Need private packages and team management tools?Check out npm Teams »

@sozialhelden/a11yjson

9.0.1 • Public • Published

A11yJSON

A11yJSON: A harmonized data schema for describing the accessibility of physical places

This repository contains a unified data format that describes the accessibility of places, facilities and services.

It’s the result of looking at accessibility datasets that we got from organizations all over the world. Our aim is to allow any other accessibility API data format to be convertible to this harmonized format in a way that makes the result easier to consume.

Our goal is to make the world more accessible for everybody — which is easier if everybody uses the same (or at least similar) language when sharing accessibility data.

This is the successor of the data schema we use for accessibility.cloud, one of the biggest data exchange providers for accessibility data, by Wheelmap.org, and other organizations. Some international sources already provide consumable data in this schema. You can find them–in most cases as open data–on https://www.accessibility.cloud.

The specification

The format is based on the GeoJSON format (RFC 7946).

We have an overview of interfaces and types, and a more extensive TypeDoc-based documentation.

Some examples:

  • Describe places of interest with the PlaceInfo and PlaceProperties interfaces
  • Describe the accessibility of a place of interest with the Accessibility interface
  • Places can have restrooms (described in every detail by the Restroom interface)
  • Places can have equipment like elevators or escalators, including realtime operational status information. Use the EquipmentProperties interface for describing facilities.

Even if you cannot adapt the whole format as part of your own indoor mapping specs, it’s a good idea to adapt single interfaces where you see fit.

Using A11yJSON as a TypeScript library

We wrote the definitions in TypeScript for compile-time validation and web compatibility. The code supports validating data records at runtime using SimpleSchema. SimpleSchema is convertible to other schemes (e.g. GraphQL, JSON LD, JSON Schema, …), if necessary.

You can integrate the library into your web or backend projects as @sozialhelden/a11yjson npm module.

Installing the npm module

  npm install --save @sozialhelden/a11yjson

Usage

// This imports only one schema interface, `PlaceInfoSchema`, from A11yJSON.
// See the documentation below for all available interfaces.
 
import { PlaceInfoSchema } from '@sozialhelden/ac-format';
 
// This could be your GeoJSON feature.
const myGeoJSONFeature = {
  geometry: { … }
  properties: { … }
};
 
// See https://github.com/aldeed/simple-schema-js for the full documentation of how validation works.
const validationContext = PlaceInfoSchema.newContext();
 
// Sanitizes the input object.
// Converts types automatically if possible, e.g. convert string values to numbers where the schema demands numbers.
const sanitizedGeoJSONFeature = PlaceInfoSchema.clean(myGeoJSONFeature);
 
// Validate the GeoJSON feature against A11yJSON’s `PlaceInfo` schema.
validationContext.validate(sanitizedGeoJSONFeature);
 
if (!validationContext.isValid()) {
  const errors = validationContext.validationErrors();
  // `errors` is a JSON object with detailled validation infos about each field in the input object.
  console.log(errors);
}

Physical quantities, rating scales and personal profiles

We found a lot of datasets claiming that places are (not) accessible for arbitrary categories of people. As an example, a data source might claim that a place is not accessible for wheelchair users, but does not mention that this is because the entrance has a step. For wheelchair users that can climb a step as long as it’s not too high, a data point like this is misleading.

A solution for better data quality is to let each individual make their own decision about the accessibility of something—if you collect or share data, measure physical attributes of places instead of target group-based data. If possible, also avoid rating scales, as their interpretation is difficult.

Internationalization (I18n)

You can localize all human-readable strings using JSON objects with IETF language tags as property names and the translations as property values:

{
  "en": "Accessibility",
  "de": "Zugänglichkeit",
  "zh-Hans": "无障碍",
  "ase": "https://www.handspeak.com/word/search/index.php?id=1643"
}

This is optional - the specification allows to simply use a string, too.

We encourage you to localize your strings—If available, you can even use IETF sign language tags (like ase for American Sign Language) for adding sign language localization using video, image or website URLs.

Bad examples with better solutions

  • Bad: ‘The place is not accessible in a wheelchair’ - Better: ‘There is one step at the entrance, its height is 2 inches’
  • Bad: ‘The sitemap is accessible for blind people’ – Better: ‘The sitemap is available in braille’ or ‘The sitemap has high contrast and uses big fonts’
  • Bad: ‘The staff is trained in accomodating people with disabilities’ – Better: Explain which facilities or services exist in detail
  • Bad: A rating that says ‘Wheelchair users gave this place 3/5 stars’ – Better: Explain the facilities wheelchair users can find at the place. Is there a step at the entrance? Is there a wheelchair-accessible toilet? Do you need a special key to use it? Etc.

Examples of helpful, measurable data points

  • ‘The entrance has an automatic door’
  • ‘The entrance has one step with 4cm height
  • ‘There is a braille sitemap with raised letters and shapes’
  • ‘There are side rails with braille navigation’
  • ‘All floors have tactile paving’
  • ‘All elevators have speech output, but no braille controls’
  • ‘The audition hall has an induction loop’
  • ‘The menu has a photo of each dish’

While we need datasets and UIs that have a simple design and are easy to understand, the data itself should define measurable properties of a place only. Interpretation should always be a separated step. Describe places, not people!

Quantities

While analyzing accessibility data sets, we often encountered unclear definitions of quantities. Should we define a length in imperial or metric units, and which prefix should we use – centimeters or meters, for example? a11yjson allows us to use any quantity+unit strings that js-quantities supports as input.

As the measurement data is SI-unit based, you can use them with any code that supports SI units:

Each attribute definition contains a preferred unit. When saving quantities, you have to specify them with a unit. You can provide measures as fixed quantities, but also with constraints and uncertainty or variance. This allows for fuzzy quantities when the measurement method is imprecise, for example when a person guesses the width of a door, or when you want to transform a data source that has averaged data calculated from measurements of more than one object.

Besides value and unit, you can save the original data value as string representation to debug conversion errors.

What if I want to make my data available, but my infrastructure does not support JavaScript/SimpleSchema/your nesting…?

If you want to make your data available on accessibility.cloud, it’s enough if your own data format is as close as possible to the attribute names / nesting described here. The more platforms use the same format, the easier it gets to share accessibility data. With accessibility.cloud, it’s possible to import data delivered in different schemas and formats.

We encourage you to implement as many attributes as possible in your project!

Contributing

This project is not complete and will never be. We're open to your suggestions and comments, no matter if you share data yourself or want to consume them from accessibility.cloudsend an email to us or create an issue or pull request!

Builds

Build Status

Keywords

none

Install

npm i @sozialhelden/a11yjson

DownloadsWeekly Downloads

50

Version

9.0.1

License

MIT

Unpacked Size

13.5 MB

Total Files

105

Last publish

Collaborators

  • avatar
  • avatar