@atb-as/config-specs

Shared types and validation for configs

Collects documentation, JSON Specifications and types for configs. Ensures consistent types and mapping for all fare product configs across projects and organisations.

Progress

[x] Fare Product Types
[x] Travel Search Filters
[x] Mobility operators
[x] Urls
[x] Harbor connection overrides
[x] Notification config
[x] Payment Types
[x] Other
[x] Reference Data
[x] Stop Signal Button Config
[ ] Schedules
[ ] Feedback Questions
[ ] App Texts

Usage

API and Types

import {ZoneSelectionMode} from '@atb-as/config-specs';

const selectedZone: ZoneSelectionMode =
  ZoneSelectionMode.parse('multiple-stop');
//> Throws error if not multiple-stop is valid.

const selectedZone2: ZoneSelectionMode =
  ZoneSelectionMode.safeParse('multiple-stop');
//> selectedZone2.success = true | false

Usage in YAML validation

# yaml-language-server: $schema=https://raw.githubusercontent.com/AtB-AS/config-specs/refs/heads/main/schema-definitions/other.json
enableTokenToggleRestrictions: true
tokenToggleMaxLimit: 3
defaultTariffZone: NOR:TariffZone:8040
vatPercent: 12

Running as CLI

Usage: npx @atb-as/config-specs -s [schema] -f [file]

Options:
      --version  Show version number                                   [boolean]
  -f, --file     file to validate                                     [required]
  -s, --schema   choose a schema
         [required] [choices: "fareProductTypeConfigs", "other", "paymentTypes",
                                                   "travelSearchFilters", "url"]
  -h, --help     Show help                                             [boolean]

Examples:
  npx @atb-as/config-specs -s other -f other.json  Validate other.json with position specification
  npx @atb-as/config-specs -s other -f other.yaml  Validate other.yaml with position specification

Install

yarn add @atb-as/config-specs

Tests and fixtures

Note contract/fixture tests in src/tests/contract-fixtures-tests. These tests should never fail unless it is very intentional. These are ment to ensure backwards compatibility with older apps.

If they fail you need to ensure that the change is intentional and that older apps refering to the data that is the cause of change is no longer in use.

Scope and goal of package

Goal of this package is to ensure data quality and consistent data across remote configuration and usage over time for multiple consumers.

This package should collect specification and validation (incl. types) for data stored in Firestore. This should ensure easier consistent validation and data quality across Firestore, Webshop and App for all organisations involved.

Collect specifications ("the standard"™)
Collect documentation ("how to use the standard")
Type generation and Schema validation generation
Input validation (Data INTO Firestore)
Data decoding / encoding validation. (Data OUT of Firestore)

Release package

After your changes are merged to the main branch:

Checkout the latest changes on main branch
Make sure you are authenticated through npm by running npm whoami
Make sure your npm user has access to publish packages to AtB's npm repo.
Run yarn build to build the package.
Tag a new release by running yarn version:

Major: Breaking change. This version require you to do code modifications after upgrading on the consumer side.
Minor: This version extends functionality.
Patch: This version affects no APIs at all, just changes to existing code.

Run npm publish to publish the package to npm.
Push to Github: git push origin main
Push tags to Github: git push origin main --tags

TODO: Packages should be automatically released when merging a PR created by release-please-action Github Action. Changelog and releases should automatically be updated.

License

EUPL-1.2