AppSummary

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/aimeat-io/json-schema/aimeat-io-app-summary-schema.json",
  "title": "AppSummary",
  "description": "Catalogue/publish view of an app (latest version), as returned by the apps endpoints.",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/aimeat-io-openapi.json#/components/schemas/AppSummary",
  "type": "object",
  "properties": {
    "owner": {
      "type": "string"
    },
    "filename": {
      "type": "string"
    },
    "version_number": {
      "type": "integer"
    },
    "manifest": {
      "type": "object",
      "description": "The app's manifest. Among its fields, `formatMd` ({ extension, action }) names the action of the owner's own extension that answers `?format=md`, read from `<meta name=\"aimeat-format-md\">` at publish. The action receives `{ format, app, lang? }`: `lang` is the reader's `?lang=` when it reads as a language tag (two or three letters, at most one subtag), so the app can answer in that language."
    },
    "size": {
      "type": "integer"
    },
    "mime_type": {
      "type": "string"
    },
    "protected": {
      "type": "boolean",
      "description": "True when an access code gates downloads"
    },
    "listing": {
      "type": "string",
      "enum": [
        "listed",
        "community",
        "unlisted"
      ],
      "description": "Where the app is listed. `listed`: every catalogue, search and other nodes. `community`: only in the catalogue listing of people signed in to this node, and nowhere public. `unlisted`: only in its owner's own list. A link opens the app in all three."
    },
    "open_to": {
      "type": "string",
      "description": "Who may open the app (PATCH /v1/apps/{filename} `open_to`). The owner reads the value they set: `anyone`, `signed-in` or `organism:<id>`. Everyone else reads the level only: `anyone`, `signed-in` or `organism`, without the organism's id. On a node set to show its content to signed-in accounts only, `anyone` still needs a sign-in."
    },
    "parked": {
      "type": "boolean",
      "description": "True when the app is off every public surface (listing community or unlisted). Kept for older clients; read `listing`."
    },
    "forkable": {
      "type": "boolean",
      "description": "True when other users are allowed to fork this app (the owner and their agents can always fork it)"
    },
    "has_draft": {
      "type": "boolean",
      "description": "True for a pending draft when the viewer owns the app or explicitly requests building=true and holds its development right. False for other viewers."
    },
    "dev_level": {
      "type": "integer",
      "enum": [
        0,
        10,
        20
      ],
      "description": "Effective development right. Present only in building=true listings."
    },
    "dev_level_name": {
      "type": "string",
      "enum": [
        "full",
        "publisher",
        "drafter"
      ]
    },
    "building_for": {
      "type": "string",
      "description": "Owner whose app the caller helps build."
    },
    "roadmap_hint": {
      "type": "string",
      "description": "Publication warning when an unshared app was published without a roadmap line."
    },
    "design_spec_hint": {
      "type": "string",
      "description": "Publication hint when a shared app has no design spec",
      "or this version moved past the version the spec was written against. Never a refusal.": null
    },
    "operator_hidden": {
      "type": "boolean",
      "description": "True when an operator has hidden the app from every public surface (visible only to its owner",
      "who cannot lift it)": null
    },
    "operator_hide_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional operator-supplied reason",
      "shown to the owner": null
    },
    "has_screenshot": {
      "type": "boolean"
    },
    "downloads": {
      "type": "integer"
    },
    "forks": {
      "type": "integer",
      "description": "Number of direct forks of this app"
    },
    "download_url": {
      "type": "string"
    },
    "screenshot_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "ai_posture": {
      "allOf": [
        {
          "$ref": "#/$defs/AppAiPosture"
        }
      ],
      "nullable": true,
      "description": "The app's AI transparency posture, or null when it has none. The `gap` member appears only for the app's own owner."
    },
    "data_map": {
      "allOf": [
        {
          "$ref": "#/$defs/DataMapStamp"
        }
      ],
      "nullable": true,
      "description": "Where this app puts what, or null when it has no map. The `gap` member appears only for the app's own owner."
    }
  },
  "$defs": {
    "AppAiPosture": {
      "type": "object",
      "description": "What a published app says about the AI inside it (TARGET-058), plus what the node observed at publish time. Stored on the app manifest. The `gap` member is OWNER-ONLY: it is the publish check telling the app's owner what is missing, and it is stripped from every response served to anyone else.\n",
      "properties": {
        "generates": {
          "type": "array",
          "description": "Modalities the app declares it generates.",
          "items": {
            "type": "string",
            "enum": [
              "text",
              "image",
              "audio",
              "video"
            ]
          }
        },
        "discloses": {
          "type": "boolean",
          "description": "Does the app show the reader an AI label?"
        },
        "publicInterest": {
          "type": "boolean",
          "description": "Does it publish on matters of public interest (a stronger labelling duty)?"
        },
        "source": {
          "type": "string",
          "enum": [
            "declared",
            "observed"
          ],
          "description": "`declared` — the app carries `<meta name=\"aimeat-ai\">`, or inherited one from the version it replaces or the app it was forked from. `observed` — the node worked it out from the source.\n"
        },
        "disclosureCallFound": {
          "type": "boolean",
          "description": "Did the published source contain a disclosure call?"
        },
        "usesAi": {
          "type": "boolean",
          "description": "Does the app request the `ai:use` scope?"
        },
        "gap": {
          "type": [
            "object",
            "null"
          ],
          "description": "OWNER-ONLY. Present when the app requests `ai:use` and tells its users nothing at all. The publish WARNS and proceeds; it never blocks (a publish that fails is a publish that gets worked around, and the app then ships with less transparency rather than more).\n",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string",
              "description": "Written for the model that built the app — it names the exact calls to add."
            },
            "at": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      }
    },
    "DataMapStamp": {
      "type": "object",
      "description": "The SUMMARY of where a published app puts what — enough for a list to render one line without opening the document. The map ITSELF, with the paragraph saying what the app is for and one sentence per row saying why the data is there, is a public memory record at `docKey`.\nNOTHING HERE IS GUESSED. An app whose builder never wrote a map is stamped `missing: true`, which is the honest answer and the one that gets a map written. An earlier version derived a map from the app's permission words, and the guess then sat exactly where the answer belonged and read like one.\nThe rows are public: where an app puts data is the promise it makes to whoever installs it, and an AI about to change the app needs it before it touches anything. `gap` is OWNER-ONLY and is stripped from every response served to anyone else.\n",
      "properties": {
        "spec": {
          "type": "string"
        },
        "form": {
          "type": "string",
          "enum": [
            "one-person",
            "private",
            "shared-with-named",
            "group",
            "organism-workspace",
            "public-service",
            "static",
            "mixed",
            "unstated"
          ],
          "description": "What shape of app this is, which decides what its map has to contain. `unstated` is a real answer and never a default the node invents.\n"
        },
        "summary": {
          "type": "string",
          "description": "One line for a list",
          "built from the rows.": null
        },
        "heldRows": {
          "type": "integer",
          "description": "Rows describing what this app holds."
        },
        "rowsWithoutWhy": {
          "type": "integer",
          "description": "Rows that say where data goes and not why it goes there."
        },
        "missing": {
          "type": "boolean",
          "description": "True when nobody has written a map for this app."
        },
        "docKey": {
          "type": "string",
          "description": "Where the full map lives."
        },
        "at": {
          "type": "string",
          "format": "date-time"
        },
        "gap": {
          "type": [
            "object",
            "null"
          ],
          "description": "OWNER-ONLY. The worst thing still missing from this map. The publish WARNS and proceeds; it NEVER blocks — a map is a statement about storage rather than a property of the bytes.\n",
          "properties": {
            "code": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "at": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      }
    }
  }
}