AirStack/common/module_schema/module.schema.json at main · castacks/AirStack · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "AirStack module manifest (module.yaml)",
  "description": "The thin module manifest from RFC #379 §2: dependencies, identity, and test metadata only. Wiring (topics, remaps, slots) deliberately does NOT live here — a module's interface is its launch file's declared args plus the interface conventions spec. Consumed by tools/validate_module.py, which interprets the draft-07 subset: type, required, properties, enum, pattern, items, additionalProperties, minLength, minItems, plus the custom x-airstack-* annotations documented in common/module_schema/README.md.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "description",
    "maintainer",
    "license",
    "type",
    "airstack_compat",
    "targets"
  ],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]*$",
      "description": "Module identity: lowercase snake_case, starts with a letter."
    },
    "description": {
      "type": "string",
      "minLength": 8,
      "description": "One-line human description shown in the registry catalog."
    },
    "maintainer": {
      "type": "string",
      "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
      "description": "Named maintainer email — required by governance (RFC #379 §8)."
    },
    "license": {
      "type": "string",
      "minLength": 1,
      "description": "SPDX-style license string; checked at registration."
    },
    "type": {
      "type": "string",
      "enum": ["isaac_extension", "ros_package", "data", "platform"],
      "description": "What kind of module this is (platform is future — RFC #380 §6)."
    },
    "airstack_compat": {
      "type": "string",
      "x-airstack-format": "semver-range",
      "description": "Semver range vs trunk .env VERSION, e.g. \">=0.19.0 <0.21.0\". Branch names and partial versions are invalid."
    },
    "targets": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "enum": ["robot", "gcs", "isaac-sim", "ms-airsim"]
      },
      "description": "Host containers this module touches."
    },
    "deps": {
      "type": "object",
      "additionalProperties": false,
      "default": {"apt": [], "pip": []},
      "description": "Dependency tier 1 (RFC #379 §6). rosdep keys live in package.xml, not here.",
      "properties": {
        "apt": {
          "type": "array",
          "items": {"type": "string", "minLength": 1}
        },
        "pip": {
          "type": "array",
          "items": {"type": "string", "minLength": 1}
        }
      }
    },
    "dockerfile": {
      "type": ["string", "null"],
      "default": null,
      "pattern": "(^|/)Dockerfile\\.module$",
      "x-airstack-format": "safe-relative-path",
      "x-airstack-check-exists": true,
      "description": "Dependency tier 2: repo-relative path to a Dockerfile.module written against ARG BASE_IMAGE, never a fixed base."
    },
    "overlay_image": {
      "type": ["string", "null"],
      "default": null,
      "minLength": 1,
      "description": "Dependency tier 3: prebuilt overlay image reference for monster deps."
    },
    "compose": {
      "type": ["string", "null"],
      "default": null,
      "x-airstack-format": "safe-relative-path",
      "x-airstack-check-exists": true,
      "description": "Optional repo-relative docker compose fragment (mounts, env)."
    },
    "assets": {
      "type": "array",
      "default": [],
      "description": "Large assets fetched to cache by `airstack sync` — no Git LFS in module repos (RFC #379 §10).",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["url", "sha256", "dest"],
        "properties": {
          "url": {
            "type": "string",
            "pattern": "^https://",
            "description": "HTTPS download URL (http:// is rejected)."
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "Lowercase hex SHA-256 of the asset."
          },
          "dest": {
            "type": "string",
            "x-airstack-format": "safe-relative-path",
            "description": "Destination path relative to the module checkout; never absolute, never escaping via '..'."
          }
        }
      }
    },
    "docs": {
      "type": "object",
      "additionalProperties": false,
      "default": {"readme": "README.md"},
      "description": "Docs entry points embedded on the versioned site (RFC #379 §9): {readme: path} or {dir: path, nav: path}.",
      "properties": {
        "readme": {
          "type": "string",
          "x-airstack-format": "safe-relative-path",
          "x-airstack-check-exists": true
        },
        "dir": {
          "type": "string",
          "x-airstack-format": "safe-relative-path",
          "x-airstack-check-exists": true
        },
        "nav": {
          "type": "string",
          "x-airstack-format": "safe-relative-path",
          "x-airstack-check-exists": true
        }
      }
    },
    "foxglove": {
      "type": ["string", "null"],
      "default": null,
      "x-airstack-format": "safe-relative-path",
      "description": "Optional Foxglove layout/panel fragment so operators can see the module in the field."
    },
    "hooks": {
      "type": "object",
      "additionalProperties": false,
      "description": "Lifecycle hooks. Contract for every hook script: idempotent, never uses sudo, writes only inside the module checkout.",
      "properties": {
        "host_setup": {
          "type": "string",
          "x-airstack-format": "safe-relative-path",
          "x-airstack-check-exists": true,
          "description": "Script run on the host after sync (precedent: the asm_optitrack module's natnet_ros2/scripts/download-natnet-sdk.sh). Must be idempotent, no sudo, and write only inside the module checkout."
        }
      }
    },
    "tests": {
      "type": "object",
      "additionalProperties": false,
      "default": {"packages": [], "marks": []},
      "description": "Test metadata: colcon unit-test packages (co-located test/) and the system-test marks the module's CI runs (RFC #379 §5).",
      "properties": {
        "packages": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "x-airstack-warn-missing-dir": true
          }
        },
        "marks": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "unit",
              "build_docker",
              "build_packages",
              "integration",
              "liveliness",
              "sensors",
              "takeoff_hover_land",
              "autonomy",
              "waypoint_flight",
              "optitrack",
              "wiring"
            ]
          }
        }
      }
    }
  }
}