{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://directory.communitybuilders.dev/data/schema.json",
  "title": "Community",
  "description": "One technology community in the Community Builders directory of Spanish tech communities. The published dataset at /data/communities.json is an array of these objects. Data is licensed CC BY 4.0: reuse is welcome with attribution to Community Builders (https://directory.communitybuilders.dev).",
  "type": "object",
  "required": [
    "id",
    "name",
    "status",
    "communityType",
    "eventFormat",
    "communityUrl"
  ],
  "properties": {
    "id": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Stable numeric identifier. `null` only while a brand-new community is awaiting id assignment on the next deploy; use the slug as the durable key if you need one."
    },
    "name": {
      "type": "string",
      "description": "Community name as it calls itself."
    },
    "status": {
      "type": "string",
      "description": "Whether the community is currently alive.",
      "enum": [
        "active",
        "inactive",
        "unknown",
        "merged"
      ],
      "x-enumDescriptions": {
        "active": "The community is running events or is otherwise alive.",
        "inactive": "No signs of activity; kept for historical reference.",
        "unknown": "Activity could not be verified.",
        "merged": "The community merged with others and no longer exists on its own; `mergedIntoId` points at the community it continues in."
      }
    },
    "lastReviewed": {
      "type": "string",
      "pattern": "^\\d{2}/\\d{2}/\\d{4}$",
      "description": "Date a human last reviewed this record, DD/MM/YYYY."
    },
    "communityType": {
      "type": "string",
      "description": "What kind of community this is.",
      "enum": [
        "tech-meetup",
        "conference",
        "umbrella-org",
        "hacklab",
        "collaborative-group",
        "meta-community",
        "mutual-aid"
      ],
      "x-enumDescriptions": {
        "tech-meetup": "Recurring local meetup or user group.",
        "conference": "Conference or single large-scale event.",
        "umbrella-org": "Organisation that hosts or coordinates several communities.",
        "hacklab": "Hacklab, makerspace or physical community space.",
        "collaborative-group": "Informal collaborative group or working group.",
        "meta-community": "Community about running communities.",
        "mutual-aid": "Mutual aid or peer-support network."
      }
    },
    "eventFormat": {
      "type": "string",
      "description": "How the community meets.",
      "enum": [
        "in-person",
        "online",
        "hybrid",
        "unknown"
      ],
      "x-enumDescriptions": {
        "in-person": "Events happen at a physical venue.",
        "online": "Events happen remotely.",
        "hybrid": "Both in-person and online.",
        "unknown": "Format could not be verified."
      }
    },
    "location": {
      "type": "string",
      "description": "Free-text place where events happen, usually \"City, Region\". Empty for online-only communities. Not the same as `geographicScope`."
    },
    "provinceId": {
      "type": "string",
      "description": "Spanish province code, when known."
    },
    "geographicScope": {
      "type": "string",
      "description": "Territory the community serves. A community can meet in Madrid and serve the whole country, so this is independent of `location`.",
      "enum": [
        "local",
        "provincial",
        "regional",
        "national",
        "international",
        "unknown"
      ],
      "x-enumDescriptions": {
        "local": "Serves a city or metropolitan area.",
        "provincial": "Serves a Spanish province.",
        "regional": "Serves an autonomous community / region.",
        "national": "Serves the whole of Spain.",
        "international": "Serves an audience beyond Spain.",
        "unknown": "Scope could not be verified."
      }
    },
    "parentId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Id of the umbrella community this one belongs to (e.g. a local chapter pointing at its national organisation)."
    },
    "organizedBy": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Ids of the communities in this directory that organise this one. Use it for a recurring event with a brand of its own run by a community (GDG Malaga organises Biznaga Fest). Both sides stay alive, so it is neither `parentId` (belonging to an umbrella) nor `mergedIntoId` (succession). Only communities listed here are enumerated: companies, sponsors and institutional support are not, so never read this as the full list of organisers. Absent when nothing is linked. The reverse side is not stored: derive it by scanning for records whose `organizedBy` contains this id."
    },
    "mergedIntoId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Only present when `status` is \"merged\": id of the community this one merged into and where its activity continues. Different from `parentId`, where both the chapter and the umbrella still exist. The reverse side is not stored: derive it by scanning for records whose `mergedIntoId` is this id."
    },
    "shortDescription": {
      "type": "string",
      "description": "One or two sentences describing the community, in its own language."
    },
    "shortDescriptionI18n": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Translations of `shortDescription`, keyed by ISO 639-1 code (for example `{\"en\": \"...\"}`). Omitted when there are none, so an absent key means nobody has translated the record yet, not that the community only works in one language -- that is what `langs` says. `shortDescription` stays canonical: it holds the text the community itself wrote, in the language it wrote it in."
    },
    "topics": {
      "type": "string",
      "description": "Legacy free-text topic list, comma separated. Prefer `tags`, which is curated."
    },
    "langs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "ISO 639-1 codes of the languages events are run in."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Topic tag ids referencing /data/tags.json (166 tags). These are ids, not labels: join against tags.json to render them. Each tag carries `label`, `description`, `category` and `synonyms`. The same catalogue is published in English at /data/tags.en.json, with identical ids and translated labels."
    },
    "openTo": {
      "type": "array",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "speakers",
          "co-organisers",
          "mentors",
          "volunteers",
          "venues",
          "collaborations",
          "sponsors"
        ]
      },
      "description": "Explicitly declared openness to volunteers (specific tasks), collaborations (joint activities between communities), co-organisers (ongoing organising roles), speakers (talks or workshops), sponsors (financial or in-kind support), venues (event spaces), or mentors (mentoring programmes). Not urgent recruitment. Empty or absent means unknown, never refusal. Populate only with explicit evidence."
    },
    "targetAudience": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Audience profile ids referencing /data/audience.json (43 profiles). English version with the same ids at /data/audience.en.json."
    },
    "matchesAllTags": {
      "type": "boolean",
      "description": "True for generalist communities: treat them as matching any topic filter. When true, `tags` is empty by design."
    },
    "matchesAllAudience": {
      "type": "boolean",
      "description": "True for communities open to any profile. When true, `targetAudience` is empty."
    },
    "contactInfo": {
      "type": "string",
      "description": "Public contact email, when published."
    },
    "communityUrl": {
      "type": "string",
      "description": "Main URL: the community's own site if it has one, otherwise its most relevant channel."
    },
    "urls": {
      "type": "array",
      "description": "Additional channels, as a list of entries. `url` is the only required field. `kind` is OMITTED when the domain already identifies the platform (x.com is Twitter), so locate a channel by its URL, not by `kind` alone; it is present when the domain cannot say it (`blog`, `rss`, `forum`, `mailingList`, `ote`, `mastodon`) or when it contradicts it. Several entries may share a `kind`: a group with its Meetup plus its own annual event are both `eventsUrl`, told apart by `label`. There is no per-platform key for event sites (Meetup/Eventbrite/Luma are all `eventsUrl`).",
      "items": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "Absolute URL of the channel."
          },
          "kind": {
            "type": "string",
            "enum": [
              "web",
              "linkAggregator",
              "github",
              "meetup",
              "eventbrite",
              "luma",
              "eventsUrl",
              "eventosWiki",
              "ote",
              "blog",
              "rss",
              "forum",
              "mailingList",
              "discord",
              "telegram",
              "whatsapp",
              "slack",
              "youtube",
              "linkedin",
              "twitter",
              "tiktok",
              "instagram",
              "facebook",
              "mastodon",
              "bluesky",
              "twitch",
              "flickr"
            ],
            "description": "What the channel is, when the domain does not say it."
          },
          "label": {
            "type": "string",
            "description": "Name to display instead of the platform name, e.g. \"DevFest Zaragoza\" for an annual event that lives alongside the group's own Meetup."
          }
        }
      }
    },
    "archivedUrls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Channels the community once had but no longer attends. Present only when non-empty. Do not surface these to users: they look alive and lead nowhere."
    },
    "thumbnailUrl": {
      "type": "string",
      "description": "Logo path relative to the site root, e.g. https://directory.communitybuilders.dev/images/foo.webp"
    },
    "latLon": {
      "type": "object",
      "description": "Coordinates of `location`; both members are null for online-only communities.",
      "properties": {
        "lat": {
          "type": [
            "number",
            "null"
          ]
        },
        "lon": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "displayOnMap": {
      "type": "boolean",
      "description": "Whether the community is plotted on the map view."
    },
    "humanValidated": {
      "type": "boolean",
      "description": "False means a person added the community but its tagging (topics, urls, status) was filled in semi-automatically and has not been checked by anyone yet. The community itself is real; the metadata is unconfirmed. Weigh it accordingly, and consider correcting it upstream."
    }
  }
}
