Skip to content

Use of Standards

Jump to bottom
Efe Feyzi Mantaroğlu edited this page Apr 16, 2026 · 2 revisions

Use of Standards

This document identifies the web and data standards adopted by Mapcess — an accessibility-focused crowdsourced mapping platform — and explains why each was chosen and how it will be integrated into the system.

Summary Table

Standard Authority Domain Integration Layer
GeoJSON — RFC 7946 IETF Geospatial coordinate encoding Backend REST API, frontend map rendering
Schema.org + JSON-LD W3C / schema.org Semantic data description Backend API responses, frontend <head>
OpenAPI 3.0 OpenAPI Initiative REST API documentation Spring Boot (springdoc-openapi)
W3C WCAG 2.1 W3C UI accessibility compliance React frontend, Flutter mobile
W3C Web Annotation Data Model W3C Comment/annotation semantics Backend Comment API + DTOs
OGC API — Features OGC Standardised geospatial query interface Backend report query endpoint

1. GeoJSON — RFC 7946

Specification: IETF RFC 7946

Which standard?

GeoJSON, as defined in IETF RFC 7946 (August 2016). It specifies a JSON encoding for geographic data structures including Point, LineString, Polygon, Feature, and FeatureCollection geometry types.

Why was it chosen?

Every core Mapcess entity — Report, RampReport, Route — carries geographic coordinates. Currently these are expressed as flat numeric fields (latitude, longitude, entryLatitude, entryLongitude) scattered across multiple DTOs. This representation has several problems:

  • It is not interoperable with GIS clients, map tile servers, or data-export pipelines without custom translation.
  • Open Route Service (ORS), the routing backend, already communicates natively in GeoJSON. The current code re-encodes the ORS LineString geometry into a proprietary encoded polyline string, then decodes it again on both the React and Flutter clients using hand-written decoders (decodePolyline in Home.jsx, custom logic in api_service.dart).
  • The GET /api/reports list response is not usable as direct input to any standard mapping tool.

Leaflet (used in the React frontend) and flutter_map (used in the Flutter client) both accept GeoJSON natively. Adopting RFC 7946 removes three custom serialisation paths and aligns the project with the de-facto standard for geographic web APIs.

How will it be integrated?

  • Replace custom polyline encoding/decoding with standard GeoJSON geometry across the API, frontend, and mobile app

2. Schema.org + JSON-LD

Specifications: Schema.org · JSON-LD 1.1 — W3C Recommendation

Which standard?

Schema.org is a structured-data vocabulary maintained by Google, Microsoft, Yahoo, and Yandex. JSON-LD (W3C Recommendation, July 2020) is its preferred serialisation, embedding a @context declaration inside standard JSON. Together they form the dominant standard for semantic markup on the web.

Relevant Schema.org types for Mapcess:

Schema.org Type / Property Maps to
schema:Place Report location
schema:GeoCoordinates Latitude / longitude pairs
schema:Report Accessibility issue report
schema:Person RegisteredUser
schema:Comment User comment on a report
schema:accessibilityHazard Obstacle tags
schema:accessibilityFeature Positive accessibility tags

Why was it chosen?

Mapcess reports describe real-world accessibility conditions at physical places. Without semantic annotation, the API returns plain JSON with application-specific field names (tag, status, agrees) that require consumers to learn the Mapcess schema. Adding JSON-LD makes report pages machine-readable by search engines and assistive technologies. This directly serves the mission: screen readers and accessibility overlays can surface accessibilityHazard and accessibilityFeature values to users with disabilities.

The Tag enum values map naturally onto Schema.org's accessibility vocabulary:

Mapcess Tag Schema.org property Value
MISSING_RAMP accessibilityHazard "noRamp"
BROKEN_ELEVATOR accessibilityHazard "brokenElevator"
NARROW_PASSAGE accessibilityHazard "narrowPassage"
WET_FLOOR accessibilityHazard "wetFloor"
CONSTRUCTION accessibilityHazard "constructionObstruction"
RAMP accessibilityFeature "ramp"
OTHER accessibilityHazard "unknown"

How will it be integrated?

Backend — ReportController.java

  • Embed structured metadata into report pages (e.g. labelling obstacles as accessibilityHazard and positive features as accessibilityFeature) so search engines and screen readers can understand the content without relying on app-specific field names

3. OpenAPI 3.0

Specification: OpenAPI Specification 3.0

Which standard?

OpenAPI Specification 3.0 (OAS 3.0), maintained by the OpenAPI Initiative under the Linux Foundation. It describes REST APIs in a machine-readable YAML or JSON document, enabling auto-generated interactive documentation, contract testing, and client code generation.

Why was it chosen?

The project already declares springdoc-openapi-starter-webmvc-ui version 3.0.2 in backend/pom.xml and OpenApiConfig.java configures a bearer JWT scheme and a Mapcess-Key API key header. A Swagger UI is therefore already accessible at runtime. However, the current configuration is skeletal:

  • The API title is "bounswe2026group1 API" with a generic description.
  • No controller has @Operation, @ApiResponse, or @Schema annotations.
  • DTO fields have no documentation surface in the generated UI.

Completing the OpenAPI documentation is low-cost (annotations only, no structural changes) and directly unblocks the mobile team's ability to generate a typed API client.

How will it be integrated?

  • Add proper metadata, descriptions, and schema annotations to all endpoints and DTOs so the mobile team can generate a typed API client and external consumers don't need to reverse-engineer the API

4. W3C WCAG 2.1

Specification: WCAG 2.1 — W3C Recommendation · Target: Level AA

Which standard?

Web Content Accessibility Guidelines 2.1 (W3C Recommendation, June 2018), Level AA conformance. WCAG 2.1 is the globally recognised standard for making web and mobile content accessible to users with disabilities, organised around four principles: Perceivable, Operable, Understandable, Robust.

Why was it chosen?

Mapcess exists specifically to serve users with mobility and accessibility needs. It would be contradictory for the application itself to be inaccessible. Currently the React frontend uses unsemantic markup (<div>, raw <button>) with Tailwind classes, and several interactive elements lack ARIA attributes or proper keyboard interaction patterns. Flutter's Semantics widget — the mechanism for VoiceOver and TalkBack support — is absent throughout the mobile codebase.

How will it be integrated?

  • Add missing ARIA attributes, semantic HTML, and keyboard support to the React frontend, and add screen reader support (Semantics widgets) to the Flutter app, since the platform's core audience has accessibility needs

5. W3C Web Annotation Data Model

Specification: Web Annotation Data Model — W3C Recommendation

Which standard?

The W3C Web Annotation Data Model (W3C Recommendation, February 2017). It defines a standard JSON-LD representation for annotations: an Annotation object that links a body (what is being said) to a target (what it is being said about), with a motivation property describing the intent.

Why was it chosen?

Mapcess Comment entities are semantically annotations on Report entities. The current CommentController directly exposes the JPA Comment entity in the API — including internal entity references like author: { id: userId } and report: { reportId } passed in the request body. This is both a design gap and a security concern (user identity should come from the authenticated JWT, not the request body). The Web Annotation model provides a well-defined, interoperable structure for this relationship and supports future evolution: "assessing" motivation for agree/disagree votes, "tagging" motivation for tag corrections.

How will it be integrated?

  • Restructure comments to follow a standard annotation format, where each comment explicitly links a body (the text) to a target (the report), and fix a security gap where user identity was passed in the request body instead of being derived from the JWT

6. OGC API — Features

Specification: OGC API — Features, Part 1: Core (17-069r4)

Which standard?

OGC API — Features, Part 1: Core (OGC Standard 17-069r4), the successor to WFS. It defines a RESTful interface for serving geospatial features using standard HTTP, JSON, and GeoJSON, with standardised query parameters for spatial and temporal filtering.

Why was it chosen?

The current GET /api/reports endpoint returns all reports as a flat array with no pagination, no bounding-box filtering, and no standard query parameters. The Report entity already has a PostgreSQL spatial index (idx_report_location on latitude, longitude) specifically to support location-based queries, but no API endpoint exposes this capability. As the crowdsourced dataset grows, loading all reports at startup is not scalable. OGC API — Features defines standard query parameters (bbox, limit, offset, datetime) that map directly onto what PostgreSQL's spatial index can serve.

How will it be integrated?

  • Replace the current all-at-once reports load with a paginated, bounding-box-filterable endpoint, so only reports within the current map viewport are fetched — making use of the spatial index that already exists in the database

Cross-Cutting Notes

Content Negotiation

All three serialisation forms — standard JSON (application/json), GeoJSON (application/geo+json), and JSON-LD (application/ld+json) — will be served from the same endpoint family using Spring's produces attribute and HTTP Accept header negotiation. This avoids URL proliferation and maintains backward compatibility with existing React and Flutter clients that send Accept: application/json.

JSON-LD Context Layering

The W3C Web Annotation model is itself expressed in JSON-LD (http://www.w3.org/ns/anno.jsonld). Comment endpoints use the Annotation context; report endpoints use the Schema.org context. These are distinct contexts on distinct resources and do not conflict.

WCAG and Schema.org Are Complementary

schema:accessibilityHazard and schema:accessibilityFeature in a <script type="application/ld+json"> block describe the content to search engines and external integrators. ARIA attributes and semantic HTML in the same page describe the UI to assistive technologies at runtime. Both layers are needed; neither replaces the other.

GeoJSON and OpenAPI

Once route geometry is a GeoJSON LineString, the OpenAPI schema for RouteResponse.geometry should reference the RFC 7946 LineString schema object (type: object, required: [type, coordinates], ...) rather than type: string. The springdoc library supports inline @Schema definitions for nested objects.

logo Mapcess

Team Members

Final Milestone Deliverables

MVP Deliverables

Lab Reports

Communication Plan

Weekly Meetings

Sub-Group Meetings

Other Meetings

Project Documentation

RAM

Scenarios and Mock-ups

Use Case Diagrams (Initial)

Use Case Diagram (Final)

Class Diagram (Final)

Sequence Diagram (Final)

Standards & Conventions

Test & Coverage Plan

Mapping API Comparison Report

MVP Demo

Final Demo

Clone this wiki locally