Publish your first feed

Two files, one response header and a validator run. Everything below is copy-paste ready and conforms to the specification it teaches — the blocks on this page are checked by the test suite against the real validator.

npx skills add Cabuya/cabuya-skill
# or, without the installer:
git clone https://github.com/Cabuya/cabuya-skill .agents/skills/cabuya

Save this first

This is a complete, conforming manifest. Replace the two URLs and the publisher id with your own, and step 1 is done.

{
  "protocol": {
    "name": "cabuya",
    "spec_version": "0.1.0"
  },
  "publisher": {
    "publisher_id": "example-app",
    "canonical_url": "https://example.org"
  },
  "conformance_target": "L2",
  "license": "CC-BY-4.0",
  "permitted_use": [
    "display",
    "aggregate"
  ],
  "feeds": [
    {
      "name": "places",
      "url": "https://example.org/feeds/places.json",
      "entity": "place",
      "profile": "core"
    }
  ]
}

1. 1

   Write the manifest

   It says who you are, what you publish and under which licence. Twelve lines is a real one, not a stub.

2. 2

   Put it at /.well-known/cabuya.json

   The path is fixed. Consumers look there and nowhere else, so there is no discovery step to implement.

3. 3

   Exclude that path from your catch-all

   Not optional. If your framework serves index.html for unknown paths, your manifest returns 200 with HTML, and every consumer treats it as absent.

4. 4

   Serialize your places into the envelope

   The envelope carries five fields and an array. Map what you already have; publish null for anything nobody has actually confirmed.

5. 5

   Run the validator until it reports no findings, then open a registry entry

   Every finding names the field and states the fix. When the run is clean, one pull request adds you to the registry.

{
  "last_updated": "2026-01-01T00:00:00Z",
  "ttl": 300,
  "version": "0.1.0",
  "publisher_id": "example-app",
  "license": "CC-BY-4.0",
  "permitted_use": [
    "display",
    "aggregate"
  ],
  "attribution": "Your App",
  "data": {
    "places": [
      {
        "id": "1",
        "publisher_id": "example-app",
        "name": "Coliseo Municipal",
        "place_kind": "shelter",
        "municipality_code": "66001",
        "address_text": "Avenida Ejemplo 12-34",
        "lat": 4.8133,
        "lon": -75.6961,
        "lifecycle_status": "active",
        "service_status": "open",
        "last_confirmed_at": null,
        "source": {
          "source_id": "example-app"
        },
        "public_url": "https://example.org/places/1"
      }
    ]
  }
}

Step 3, per stack

Find yours, apply the single line, then request the URL and confirm that the response is JSON.

One header, which a file cannot carry

Two static files are schema-valid and are not yet L2. The feed also has to be readable from a browser, and that is a response header your host sets — not something you can put inside the JSON.

/*
  Access-Control-Allow-Origin: *

/*
  Access-Control-Allow-Origin: *

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" }
      ]
    }
  ]
}

location /.well-known/cabuya.json {
  add_header Access-Control-Allow-Origin *;
}

location /feeds/ {
  add_header Access-Control-Allow-Origin *;
}

<FilesMatch "cabuya\.json$|\.json$">
  Header set Access-Control-Allow-Origin "*"
</FilesMatch>

{
  "CORSRules": [
    {
      "AllowedOrigins": ["*"],
      "AllowedMethods": ["GET", "HEAD"],
      "AllowedHeaders": ["*"]
    }
  ]
}

Before you publish: the one decision that is yours

Cabuya carries places, not people. Review the fields you are about to map and confirm that none of them holds a person’s name, a personal phone or email, an individual case, or a moderation verdict about an individual.

Run it

Point the validator at your manifest URL. It follows the feeds it declares, and reports what it found.

Open the validator

The paste mode runs the same engine in your browser, with nothing uploaded. URL checking — which also measures the transport behaviour — needs a server, and that part is still being built. The command line does both today:

npx @cabuya/validator validate https://example.org/.well-known/cabuya.json

How long this actually takes

Five minutes is the honest number for the path above: two static files and one header, copied, edited and uploaded. It is a real conformance level — L2 — and it is genuinely useful to consumers.

Mapping a live database into the schema is an afternoon, sometimes two: your statuses have to be reconciled with the shared vocabulary, and somebody has to decide what your data actually means. That work is not avoidable, and stating it here is better than leaving it to surface at step 4.

Developers