{"id":38247177,"url":"https://github.com/blues/notecard-schema","last_synced_at":"2026-02-20T00:01:21.730Z","repository":{"id":289895075,"uuid":"970291024","full_name":"blues/notecard-schema","owner":"blues","description":"Notecard API JSON Schema ","archived":false,"fork":false,"pushed_at":"2026-02-06T17:53:17.000Z","size":1234,"stargazers_count":1,"open_issues_count":8,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-07T01:54:30.255Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://blues.github.io/notecard-schema/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blues.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-21T19:33:04.000Z","updated_at":"2026-02-02T21:16:07.000Z","dependencies_parsed_at":"2025-06-13T16:21:41.786Z","dependency_job_id":"794c0002-8c30-4c8b-b214-02d0b3e1fdb7","html_url":"https://github.com/blues/notecard-schema","commit_stats":null,"previous_names":["blues/notecard-schema"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/blues/notecard-schema","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotecard-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotecard-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotecard-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotecard-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blues","download_url":"https://codeload.github.com/blues/notecard-schema/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blues%2Fnotecard-schema/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29637400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"ssl_error","status_checked_at":"2026-02-19T22:32:38.330Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T01:24:32.930Z","updated_at":"2026-02-20T00:01:21.702Z","avatar_url":"https://github.com/blues.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Notecard API Schema\n\nThis repository contains the JSON schemas for the Notecard API.\n\n## Table of Contents\n\n- [Notecard API Schema](#notecard-api-schema)\n  - [Table of Contents](#table-of-contents)\n  - [Development](#development)\n  - [Adding a new schema](#adding-a-new-schema)\n    - [Custom Fields](#custom-fields)\n      - [`annotations`](#annotations)\n      - [`deprecated`](#deprecated)\n      - [`minApiVersion`](#minapiversion)\n      - [`samples`](#samples)\n      - [`skus`](#skus)\n      - [`sub-descriptions`](#sub-descriptions)\n  - [Updating the schema version](#updating-the-schema-version)\n  - [Running the tests](#running-the-tests)\n\n## Development\n\n- Python 3.12+\n- `pipenv`\n\n```bash\npipenv install --dev\npipenv run setup-hooks  # Install pre-commit hooks\npipenv run pytest\n```\n\nPre-commit hooks will automatically validate and format files before each commit.\n\n## Adding a new schema\n\nUse the `scripts/create_api.py` script to create a new schema.\n\n```bash\n# Example for card.example\npipenv run python scripts/create_api.py card.example\n```\n\nThis will create a new schema file with the necessary metadata and a basic structure that you can then fill in with the specific details of the API request or response.\n\n1. This will create the `card.example.req.notecard.api.json` and `card.example.rsp.notecard.api.json` schemas.\n\n2. Additionally, the script will create a test suite for both the request and response schemas in the `tests` directory.\n\n3. Update these schemas with the specific details of the new API request or response.\n\n### Custom Fields\n\nThe composition of all JSON schemas is also used to generate the\n[Notecard API Reference Documentation](https://dev.blues.io/api-reference/).\nIn order to faithfully recreate the original documentation, several new fields\nwere created to capture any information that falls outside the scope of the\ntraditional JSON schema.\n\n#### `annotations`\n\nAnnotations, such as \"Deprecated\", \"Note\" or \"Warning\" should be captured as\n`deprecated`, `note` and `warning`, respectively.\n\nExample shown from `hub.signal`:\n\n```json\n\"annotations\": [\n    {\n        \"title\":\"note\",\n        \"description\":\"See our guide to Using Inbound Signals for more information on how to set up a host microcontroller or single-board computer to receive inbound signals.\"\n    },\n    {\n        \"title\":\"warning\",\n        \"description\":\"A Notecard must be in [continuous mode](https://dev.blues.io/api-reference/notecard-api/hub-requests/latest/#hub-set) and have its `sync` argument set to `true` to receive signals.\"\n    }\n]\n```\n\n#### `deprecated`\n\nA boolean indicating if the API is deprecated.\n\nExample shown from `card.attn`:\n\n```json\n\"deprecated\": true\n```\n\n#### `minApiVersion`\n\nA string indicating the minimum API version that the API is compatible with.\nThis can be applied at the top level of the schema, at the level of a specific property, or at the level of a specific sub-description.\nWhen this generates blues.dev documentation, the version dropdown will hide any content that is below the specified version.\n\nExample shown from `auxgpio` in `card.attn`:\n\n```json\n{\n    \"const\": \"auxgpio\",\n    \"description\": \"When armed, causes ATTN to fire if an AUX GPIO input changes. Disable by using `-auxgpio`.\",\n    \"skus\": [\n        \"CELL\",\n        \"CELL+WIFI\",\n        \"LORA\",\n        \"WIFI\"\n    ],\n    \"minApiVersion\": \"3.4.1\"\n},\n```\n\n#### `samples`\n\nAn array of objects representing each of the JSON examples provided.\nAll `req` schemas must have a sample.\nFor `rsp` schemas, samples are optional if there is no response body.\n\nExample shown from `card.attn`:\n\n```json\n\"samples\": [\n    {\n        \"title\": \"Connected\",\n        \"description\": \"Configure the Notecard to perform an interrupt on a successful connection to Notehub.\",\n        \"json\": \"{\\\"req\\\":\\\"card.attn\\\",\\\"mode\\\":\\\"arm,connected\\\"}\"\n    },\n    {\n        \"title\": \"Files\",\n        \"description\": \"Configure the Notecard to perform an interrupt on the `data.qi` and `my-settings.db` Notefiles.\",\n        \"json\": \"{\\\"req\\\":\\\"card.attn\\\",\\\"mode\\\":\\\"arm,files\\\",\\\"files\\\":[\\\"data.qi\\\",\\\"my-settings.db\\\"]}\"\n    },\n    {\n        \"title\": \"Location\",\n        \"description\": \"Configure the Notecard to perform an interrupt when the Notecard makes a position fix.\",\n        \"json\": \"{\\\"req\\\":\\\"card.attn\\\",\\\"mode\\\":\\\"arm,location\\\"}\"\n    },\n    ...\n]\n```\n\nThe value of `json` appears as the JSON code example, the `title`\nvalue appears as the tab header when multiple examples are present, and\n`description` is provided as a caption to the example code block.\n\n#### `skus`\n\nAn array indicating Notecard compatibility at both the API and parameter level.\n\nSome APIs and parameters are reserved for specific Notecard SKUs (e.g.\n`card.wifi` is used to configure the WiFi connectivity of WiFi compatible\nNotecards).\nAll APIs and parameters are considered valid by ALL Notecards,\nhowever, they will be discarded when provided to an incompatible SKU.\n\nExample shown from `card.transport`:\n\n```json\n{\n    \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n    \"$id\": \"https://raw.githubusercontent.com/blues/notecard-schema/master/card.transport.req.notecard.api.json\",\n    \"title\": \"card.transport Request Application Programming Interface (API) Schema\",\n    \"description\": \"Specifies the connectivity protocol to prioritize on the Notecard Cell+WiFi, or when using NTN mode with Starnote and a compatible Notecard.\",\n    \"type\": \"object\",\n    \"version\": \"0.2.1\",\n    \"apiVersion\": \"9.1.1\",\n    \"skus\": [\"CELL\",\"CELL+WIFI\",\"WIFI\"],\n    \"properties\": {\n        \"method\": {\n            \"description\": \"The connectivity method to enable on the Notecard.\",\n            \"type\": \"string\",\n            \"enum\": [\n                \"-\",\n                \"cell\",\n                \"cell-ntn\",\n                \"dual-wifi-cell\",\n                \"ntn\",\n                \"wifi\",\n                \"wifi-cell\",\n                \"wifi-cell-ntn\",\n                \"wifi-ntn\"\n            ],\n            \"sub-descriptions\": [\n                {\n                    \"const\": \"-\",\n                    \"description\": \"Resets the transport mode to the device default.\",\n                    \"skus\": [\"CELL\",\"CELL+WIFI\",\"WIFI\"]\n                },\n                {\n                    \"const\": \"cell\",\n                    \"description\": \"Enables cellular only on the device.\",\n                    \"skus\": [\"CELL\",\"CELL+WIFI\"]\n                },\n                {\n                    \"const\": \"cell-ntn\",\n                    \"description\": \"Prioritizes cellular connectivity while falling back to NTN if a cellular connection cannot be established.\",\n                    \"skus\": [\"CELL\",\"CELL+WIFI\"]\n                },\n                {\n                    \"const\": \"dual-wifi-cell\",\n                    \"deprecated\": true,\n                    \"description\": \"Deprecated form of `\\\"wifi-cell\\\"`\",\n                    \"skus\": [\"CELL+WIFI\"]\n                },\n                ...\n            ]\n        },\n        ...\n    }\n}\n```\n\n\u003e _**NOTE:** `skus` is valid at any level the `description` field is also valid._\n\n#### `sub-descriptions`\n\nAn array of objects providing a detailed description of enumerated or pattern\nmatching values.\n\nIt can be difficult, or even impossible, to provide a description for enumerated\nor pattern matching values.\nIn such cases, an additional object can be useful to\nprovide a description and other details for each of the valid values.\n\nExample shown from `card.attn`:\n\n```json\n\"mode\": {\n    \"description\": \"A comma-separated list of one or more of the following keywords. Some keywords are only supported on certain types of Notecards.\",\n    \"type\": \"string\",\n    \"pattern\": \"^(?:-all|-env|-files|-location|-motion|-usb|arm|auxgpio|connected|disarm|env|files|location|motion|motionchange|rearm|signal|sleep|usb|watchdog|wireless)(?:,\\\\s*(?:-all|-env|-files|-location|-motion|-usb|arm|auxgpio|connected|disarm|env|files|location|motion|motionchange|rearm|signal|sleep|usb|watchdog|wireless))*\\\\s*$\",\n    \"sub-descriptions\": [\n        {\n            \"const\": \"\",\n            \"description\": \"Fetches currently pending events in the \\\"files\\\" collection.\",\n            \"skus\": [\"CELL\",\"CELL+WIFI\",\"WIFI\"]\n        },\n        {\n            \"const\": \"arm\",\n            \"description\": \"Clear \\\"files\\\" events and cause the ATTN pin to go LOW. After an event occurs or \\\"seconds\\\" has elapsed, the ATTN pin will then go HIGH (a.k.a. \\\"fires\\\"). If \\\"seconds\\\" is 0, no timeout will be scheduled. If ATTN is armed, calling `arm` again will disarm (briefly pulling ATTN HIGH), then arm (non-idempotent).\",\n            \"skus\": [\"CELL\",\"CELL+WIFI\",\"LORA\",\"WIFI\"]\n        },\n        {\n            \"const\": \"auxgpio\",\n            \"description\": \"When armed, causes ATTN to fire if an AUX GPIO input changes. Disable by using `-auxgpio`.\",\n            \"skus\": [\"CELL\",\"CELL+WIFI\",\"LORA\",\"WIFI\"]\n        },\n        ...\n    ]\n},\n```\n\n## Updating the schema version\n\nTo update the version of Notecard firmware that the schemas are compatible with,\nrun the following command:\n\n```bash\npython scripts/update_schema_version.py --property apiVersion --target-version 9.1.2 --pattern \"card.attn.*\"\n```\n\nThis will update the `apiVersion` in all files that match the pattern `card.attn.*`.\n\n## Running the tests\n\n```bash\npipenv install --dev\npipenv run pytest\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblues%2Fnotecard-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblues%2Fnotecard-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblues%2Fnotecard-schema/lists"}