@the-rfp-hub/standard 1.0.0

package/schemas/v1.0.0/BENCHMARK.md

@@ -0,0 +1,160 @@
+# RFP Hub Standard v1.0.0 — Real-Data Benchmark
+
+Validation of the standard against **real-world funding-opportunity data** from a production
+funding aggregator's public API, plus a ranked benchmark set for schema/CLI testing.
+
+**This document is informative** ([`NORMATIVE.md`](../../NORMATIVE.md)). It records a
+measurement, not a rule.
+
+> ⚠️ **Two measurements, two shapes.** The 311-entry pull below was run against the schema **as
+> it stood before the 2026-07-27 in-place re-cut**, and has **not** been re-run. The 28 committed
+> example documents **have** been converted to the re-cut shape and re-validated. Read the
+> corpus-wide numbers as evidence about the data model, and the fixture numbers as evidence about
+> the current schema. See the [field mapping table](../../CHANGELOG.md#field-mapping-old--new).
+
+## Result
+
+| Metric | Value | Measured against |
+|---|---|---|
+| Unique entries pulled | **311** | pre-re-cut shape |
+| Mapped to source-neutral examples + validated | **289 / 289 valid (0 failures)** | pre-re-cut shape |
+| Curated benchmark fixtures | **28** (in [`examples/`](./examples)) | **re-cut shape — 28/28 valid** |
+| Funding types covered by fixtures | grant, hackathon, bounty, accelerator, rfp | — |
+
+289 of the 311 pulled entries mapped to public-source, source-neutral examples and all validated
+with 0 failures — evidence that the data model is faithful to a real funding corpus. The
+remaining ~22 were set aside for lacking a public original-posting URL or to keep the sample free
+of any one aggregator's branding. Example ids use a neutral `fundingmap:` namespace.
+
+The **28 committed fixtures are the live claim**: they were converted field-by-field to the
+re-cut shape and all 28 validate against the current
+[`opportunity.schema.json`](./opportunity.schema.json).
+
+```bash
+npx rfphub-validate packages/standard/schemas/v1.0.0/examples
+# 28 passed, 0 failed
+```
+
+## What the re-cut conversion did to these 28 documents
+
+Mechanical, and lossless where a real value existed. Each move follows a row in the
+[field mapping table](../../CHANGELOG.md#field-mapping-old--new):
+
+- **`type` → `fundingType`**, and each document's type block re-keyed to match. No document
+  carried a second, non-matching type block, so the newly enforced one-block-per-type rule cost
+  nothing here.
+- **`organization` → `sponsoringOrganizations[0]`** — a wrap, no data change. No fixture needed
+  `operatingOrganizations`.
+- **`source.url` has no successor.** Where a document had no `applicationUrl`, the old source URL
+  became the `applicationUrl` — it was the only link-back target left. Where `applicationUrl`
+  already pointed somewhere else, the source URL was preserved in **`resourceLinks`** rather than
+  dropped: **6 of the 28 documents** carry one for that reason.
+- **Hackathon date folding.** `registrationDeadline`, `submissionDeadline`, `startDate` and
+  `endDate` all folded into `deadlines[]` with labels `registration` / `submission` /
+  `event start` / `event end`; `closesAt` and `rfp.proposalDeadline` folded in as `application`.
+  Across the corpus this produced **28 `application`, 18 `registration`, 19 `event start` and 19
+  `event end`** entries — which is exactly why a consumer must select by label: on 19 of these
+  documents `deadlines[0]` is an event boundary, not a deadline.
+- **`funding.totalBudget` → `budget`**, `amountDistributed` → `allocated`. Only one document had
+  a non-zero `funding.awardsToDate`, a field with no successor; that value was preserved under
+  **`extensions`** rather than deleted. It is the only fixture using `extensions`.
+- No fixture exercises `milestones[]`, `eligibility`, `serviceAgreement` or `prerequisites` —
+  the source corpus carries none of them. Those fields are exercised by the
+  [conformance suite](../../conformance/v1.0.0), not by this benchmark.
+
+## Methodology (original pull)
+
+- **Source:** a production funding aggregator's public REST API (`isValid=accepted`, sorted by
+  recency); 3 general pages (100/page) plus one page per type for diversity, deduped to 311.
+- **Mapping:** each entry mapped to the Standard's public shape; source-system internal fields
+  are dropped (the standard is source-agnostic).
+- **Validation:** ajv 8 (`ajv/dist/2020`) + `ajv-formats`, `strict: true, strictRequired: false`.
+- **Fill score** — count of *populated* Standard fields (scalar leaves + non-empty arrays and
+  their items), excluding the always-present `specVersion`/`id`/type discriminator and
+  `extensions`. Higher = richer entry, better for exercising schema breadth.
+- **Activity score** — `status` weight (`open` 4 / `upcoming` 3 / `closed` 1 / `archived` 0)
+  `+3` if the application deadline is in the future, `+1` if `opensAt` is in the future,
+  `+` recency (up to `+4`, linearly decaying over 1 year from `updatedAt`). *(Computed on the
+  pre-re-cut single `closesAt` scalar; under the re-cut shape the same score would read the
+  `application`-labelled entry of `deadlines[]`.)*
+
+Both scores are **ranking heuristics for choosing fixtures**, not quality metrics of the
+standard, and neither is normative.
+
+## Per-type coverage (original pull)
+
+| Type | Sampled | Valid |
+|---|--:|--:|
+| grant | 99 | 99 |
+| hackathon | 130 | 130 |
+| bounty | 42 | 42 |
+| accelerator | 16 | 16 |
+| rfp | 2 | 2 |
+| **vc_fund** | **0** | — |
+
+> ⚠️ **`vc_fund` coverage gap:** there are **zero** VC-fund entries in the source data, so the
+> `vc_fund` block still cannot be benchmarked against real data. It is covered by the conformance
+> suite only; real VC-fund entries should be added during later seeding. `rfp` is also thin
+> (2 entries) — worth expanding given this is the *RFP* Hub.
+
+## Benchmark fixture set
+
+The 28 fixtures in [`examples/`](./examples) are the top entries by fill, with type diversity
+injected (≥1 of each available type): **19 hackathon, 6 grant, 1 bounty, 1 accelerator, 1 rfp**.
+They serve as (a) the real-data validation corpus, (b) golden inputs for the `rfphub-validate`
+CLI, and (c) realistic seed candidates for the public dataset. They are **examples, not
+conformance cases** — the pass/fail rule documents live in
+[`conformance/v1.0.0/`](../../conformance/v1.0.0). The single best all-round benchmark entry is
+**Prezenti Boost Pool S2** (`fundingmap:1459`) — open, future deadline, and high fill.
+
+### Top 15 by FILL (most complete entries, original pull)
+
+| # | Fill | Activity | Type | Status | Name | id |
+|--:|--:|--:|---|---|---|---|
+| 1 | 73 | 2.86 | hackathon | archived | Electrothon 8.0 | fundingmap:1200 |
+| 2 | 49 | 2.86 | hackathon | archived | HACKANOVA 5.O | fundingmap:1197 |
+| 3 | 46 | 3.11 | hackathon | archived | ETHGlobal Cannes 2026 | fundingmap:1095 |
+| 4 | 42 | 10.58 | grant | open | Prezenti Boost Pool S2 | fundingmap:1459 |
+| 5 | 39 | 2.92 | hackathon | archived | HackByte 4.0 | fundingmap:1210 |
+| 6 | 37 | 3.13 | hackathon | archived | Hack-Helix | fundingmap:1340 |
+| 7 | 36 | 9.81 | hackathon | upcoming | ETHGlobal Lisbon 2026 | fundingmap:1093 |
+| 8 | 36 | 9.81 | hackathon | upcoming | ETHGlobal Mumbai | fundingmap:1091 |
+| 9 | 36 | 3.88 | hackathon | archived | ETHGlobal New York 2026 | fundingmap:1094 |
+| 10 | 35 | 4.58 | grant | closed | Prezenti Mint Round | fundingmap:600 |
+| 11 | 34 | 3.44 | hackathon | archived | Locus' Paygentic Hackathon - #2 | fundingmap:1389 |
+| 12 | 34 | 3.22 | hackathon | archived | Locus' Paygentic Hackathon - #1 | fundingmap:1356 |
+| 13 | 33 | 10.58 | grant | open | Prezenti Anchor Pool | fundingmap:1458 |
+| 14 | 33 | 3.87 | grant | closed | Build Agents for the Real World Hackathon V2 | fundingmap:1059 |
+| 15 | 33 | 3.44 | hackathon | archived | Locus' Paygentic Hackathon - #4 | fundingmap:1430 |
+
+### Top 15 by ACTIVITY (most live opportunities, original pull)
+
+| # | Activity | Fill | Type | Status | Name | id |
+|--:|--:|--:|---|---|---|---|
+| 1 | 10.91 | 27 | hackathon | upcoming | FutureForge Hackathon 2026 | fundingmap:1494 |
+| 2 | 10.91 | 25 | hackathon | upcoming | MicroCraft - Vibeathon | fundingmap:1493 |
+| 3 | 10.91 | 25 | hackathon | upcoming | Ignisys 1.O | fundingmap:1495 |
+| 4 | 10.81 | 29 | hackathon | upcoming | DSU DEVHACK 3.0 | fundingmap:1488 |
+| 5 | 10.81 | 25 | hackathon | upcoming | Hack On Hills 8.0 | fundingmap:1490 |
+| 6 | 10.81 | 25 | hackathon | upcoming | Hack4Brahma 2.0 | fundingmap:1489 |
+| 7 | 10.81 | 25 | hackathon | upcoming | HackNex Season 2 | fundingmap:1483 |
+| 8 | 10.81 | 25 | hackathon | upcoming | SheBuilds Chennai Hack | fundingmap:1487 |
+| 9 | 10.81 | 25 | hackathon | upcoming | ccuhacks | fundingmap:1478 |
+| 10 | 10.81 | 25 | hackathon | upcoming | HACKER HOUSE GOA 2026 | fundingmap:1480 |
+| 11 | 10.58 | 42 | grant | open | Prezenti Boost Pool S2 | fundingmap:1459 |
+| 12 | 10.58 | 33 | grant | open | Prezenti Anchor Pool | fundingmap:1458 |
+| 13 | 10.24 | 25 | hackathon | upcoming | Citadel Hackathon - Season 1 | fundingmap:1390 |
+| 14 | 10.05 | 24 | grant | open | infraBUIDL(AI) | fundingmap:938 |
+| 15 | 10.05 | 15 | grant | open | Arbitrum Audit Program | fundingmap:1320 |
+
+*Both scores are as measured on the pre-re-cut shape at pull time. The re-cut removed some fields
+and added others, so the absolute fill numbers would shift, and activity scores decay with the
+calendar; the ranking that selected these fixtures would not change materially.*
+
+## Reproduce
+
+An internal pull/map/rank script reads a production funding aggregator's public API, maps each
+entry to the Standard, validates with ajv, and ranks by fill/activity. Raw pulled data and full
+scored rankings stay local (reproducible from the public API) and are not committed. Re-running
+it against the re-cut shape is worthwhile before the next cut, and would replace the pre-re-cut
+figures above.

package/schemas/v1.0.0/CROSSWALK.md

@@ -0,0 +1,200 @@
+# RFP Hub Standard ↔ DAOIP-5 ↔ schema.org/Grant
+
+The project's brief is to **build on** the **DAOIP-5 Grants Metadata Standard** and
+**schema.org/Grant** rather than start from scratch. This crosswalk documents how the RFP Hub
+Standard v1.0.0 maps onto both, so a consumer can translate between them.
+
+**This document is informative** — the schema is normative
+([`NORMATIVE.md`](../../NORMATIVE.md)). It is also corrigible: a wrong mapping row can be fixed
+outside the release cycle.
+
+- **schema.org/Grant** is intentionally minimal (a handful of properties on `Thing` + `funder`,
+  `sponsor`, `amount`, `fundedItem`). Every one of its fields has a clean RFP Hub equivalent.
+- **DAOIP-5** is a JSON-LD family of objects: **Grant System** (the administering body),
+  **Grant Pool** (an open funding opportunity), **Project**, **Application**. The RFP Hub
+  **Opportunity** is closest to a **Grant Pool**; our **Organization** ≈ a **Grant System**.
+  DAOIP-5 is grant-centric, so our non-grant types (hackathon/bounty/accelerator/vc_fund) and
+  several fields extend beyond it.
+
+> ⚠️ **v1.0.0 was re-cut in place on 2026-07-27** and this crosswalk was reissued with it. If you
+> are holding a copy of this file that maps `organization`, `source.url`, `closesAt`,
+> `funding.totalBudget` or `grant.fundingMechanism`, it predates the re-cut — see
+> the [field mapping table](../../CHANGELOG.md#field-mapping-old--new) in `CHANGELOG.md`.
+
+## Field mapping (Opportunity)
+
+"—" means **no equivalent exists** in that standard. It is not shorthand for "not yet mapped".
+
+### Identity and description
+
+| RFP Hub v1.0.0 | schema.org/Grant | DAOIP-5 (Grant Pool unless noted) |
+|---|---|---|
+| `id` | `identifier` | `id` |
+| `title` | `name` | `name` |
+| `description` | `description` | `description` |
+| `summary` | `disambiguatingDescription` | — |
+| `fundingType` (6 values) | — (`Grant` is the only type) | — (a Grant Pool is a grant by definition) |
+| `status` (4 values) | — | `isOpen` (boolean) — **lossy both ways**: four lifecycle values collapse to one boolean, and `upcoming` vs `open` is unrecoverable |
+| `specVersion` | `schemaVersion` | — |
+
+### Organisations
+
+| RFP Hub v1.0.0 | schema.org/Grant | DAOIP-5 |
+|---|---|---|
+| `sponsoringOrganizations[]` | `funder` (Organization) — **repeatable, so the array maps cleanly** | **Grant System** (the administering body) |
+| `sponsoringOrganizations[0].name` | `funder.name` | grant system `name` |
+| `operatingOrganizations[]` | `sponsor` — **loose**: schema.org's `sponsor` is another funding-side role, not an operator. The JSON-LD context uses it as the nearest available term; a consumer that needs "who runs intake" must read the RFP Hub field | — |
+| `organization.contacts[]` | `contactPoint` | — |
+| `organization.logoUrl` / `bannerUrl` | `logo` / `image` | — |
+
+### Money
+
+| RFP Hub v1.0.0 | schema.org/Grant | DAOIP-5 |
+|---|---|---|
+| `funding.budget` | `amount` (MonetaryAmount) | `totalGrantPoolSize[].amount` |
+| `funding.currency` | `amount.currency` | `totalGrantPoolSize[].denomination` |
+| `funding.allocated` (committed to date) | — | — |
+| `funding.minAward` / `maxAward` | — | — |
+| `milestones[]` | — | — (no Grant Pool equivalent) |
+| `bounty.reward`, `hackathon.prizes[]`, `accelerator.funding` | `amount` (loosely) | — |
+
+**Cardinality divergence.** DAOIP-5's `totalGrantPoolSize` is an **array** of
+`{amount, denomination}`; the RFP Hub envelope is **single-currency by design**. Exporting to
+DAOIP-5 emits a one-element array. Importing from DAOIP-5 takes the primary amount and must put
+any further denominations in `description` or `extensions` — that direction is lossy, and
+deliberately so.
+
+### Dates
+
+| RFP Hub v1.0.0 | schema.org/Grant | DAOIP-5 |
+|---|---|---|
+| `deadlines[]` where `label = "application"` | — | `closeDate` |
+| `deadlines[]` — every other label (`registration`, `submission`, `event start`, `event end`, `community feedback`) | — | — |
+| `deadlines[].type = "rolling"` | — | — (DAOIP-5 has no rolling form; `isOpen` carries what it can) |
+| `opensAt` | `startDate` | — |
+| `postedAt` | `datePublished` | — |
+| `createdAt` / `updatedAt` | `dateCreated` / `dateModified` | — |
+
+**Cardinality divergence.** DAOIP-5 has one scalar `closeDate`; the RFP Hub has an array of
+labelled deadlines. Exporting takes the earliest future `application` deadline. Importing yields
+a single `{type: "fixed", date, label: "application"}` entry — every other deadline the source
+had, if it had any, was already lost before it reached us.
+
+### Eligibility, requirements, links
+
+| RFP Hub v1.0.0 | schema.org/Grant | DAOIP-5 |
+|---|---|---|
+| `applicationUrl` | `url` | `applicationsURI` |
+| `website` | `sameAs` | — (`governanceURI` is a different thing) |
+| `socialLinks` | `sameAs` | — |
+| `resourceLinks` | `citation` (loose) | — |
+| `eligibility` (open key→value map) | `eligibleCustomerType` (loose) | — |
+| `prerequisites` | `competencyRequired` (loose) | — |
+| `serviceAgreement` | — | — |
+| `rfp.scope` / `rfp.requirements` | — | — |
+| `categories` / `tags` | `about` / `keywords` (loose) | — |
+| `ecosystems` / `networks` | — | — (RFP Hub extension) |
+
+### Grant mechanics and provenance
+
+| RFP Hub v1.0.0 | schema.org/Grant | DAOIP-5 |
+|---|---|---|
+| `grant.fundingMechanisms[]` | — | `grantFundingMechanism` — **singular there, array here** |
+| `grant.programModel` | — | — |
+| `grant.milestoneBased` / `grant.recurring` | — | — |
+| `source.publisher` | `publisher` | — |
+| `source.submittedBy` | `contributor` | — |
+| `source.submittedAt` | `dateCreated` | — |
+| `source.snapshotUrl` | `archivedAt` | — |
+| `source.ingestedVia` / `originalId` / `verifiedAgainstSource` / `verifiedAt` | — | — (RFP Hub provenance extension) |
+| `extensions` | — | `extensions` |
+
+**Cardinality divergence.** `grant.fundingMechanisms` is an array (mechanisms co-occur — a fixed
+grant plus a matching grant in the same program); DAOIP-5's `grantFundingMechanism` is a scalar.
+Export takes the first element or joins them; either choice loses information, so the export
+adapter should pick one and document it. Value-level alignment is unchanged: `retroactive`,
+`proactive`, `streaming`, `quadratic`, `matching`, `other` map onto DAOIP-5's vocabulary
+("Retroactive", "Direct Grants", "Quadratic Funding", …).
+
+### Type blocks beyond both standards
+
+`hackathon`, `bounty`, `accelerator` and `vc_fund` have **no equivalent** in either standard.
+DAOIP-5 models grants; schema.org models `Grant`. Everything inside those four blocks —
+tracks, prizes, team sizes, check sizes, investment stages, equity, batch size — is an RFP Hub
+extension and does not round-trip.
+
+Self-identification keys (`$schema`, `@context`, `@type`) are JSON Schema and JSON-LD machinery,
+not domain fields; they have no crosswalk row.
+
+## Alignment status
+
+- ✅ **Crosswalk verified** against the published DAOIP-5 spec (Grant System + Grant Pool
+  objects) and schema.org/Grant. **Every schema.org/Grant property and every DAOIP-5 Grant Pool
+  field still has an RFP Hub equivalent** — alignment survived the re-cut in that direction.
+- ⚠️ **The earlier claim that "no v1.0.0 field had to change to align" no longer holds, and
+  should not be repeated.** Fields *did* change — not to chase alignment, but because the
+  2026-07-27 design decisions re-cut the shape. Three mappings were reissued as a direct
+  consequence:
+  - `source.url` → the `sameAs` sense **has no successor**. `applicationUrl` carries the
+    `schema:url` / `applicationsURI` sense alone; a publisher who needs the original posting
+    on the record puts it in `resourceLinks`, which maps only loosely to `schema:citation`.
+  - `organization` → `sponsoringOrganizations[]`, which maps *better* than before: schema.org
+    carries `funder` **and** `sponsor`, and both are repeatable.
+  - `closesAt` → `deadlines[]`, which maps *worse* than before: one scalar became a labelled
+    array and only the `application` label round-trips to `closeDate`.
+
+  See the [field mapping table](../../CHANGELOG.md#field-mapping-old--new) for the full
+  field-by-field record and
+  [`adr/0002`](../../../../adr/0002-v-next-field-recut.md) for why.
+- ✅ **JSON-LD `@context` shipped** — [`context.jsonld`](./context.jsonld), covering every
+  top-level property of the re-cut shape (CI fails on context↔schema drift in either direction).
+  Term IRIs are **versionless** (`https://github.com/The-RFP-Hub/the-rfp-hub/ns/draft/rfp#`, provisional
+  pending a canonical domain); the context *document* is what
+  gets versioned. Every field with no schema.org or DAOIP-5 equivalent resolves under the RFP Hub
+  vocabulary, so nothing is dropped when a document is read as linked data.
+- ⬜ **DAOIP-5 `grantPools` export** (optional, planned) — a one-way *output adapter* that emits
+  grant-type opportunities as DAOIP-5 `grantPools` JSON, applying the three cardinality
+  reductions above. This is an export *format*, **not** a prerequisite for the standard being
+  aligned. See [`ARTIFACTS.md`](../../ARTIFACTS.md).
+
+## Using the JSON-LD context
+
+A document may carry `@context` and `@type` at the top level and **still validate** — the
+three self-identification keys are permitted against `additionalProperties: false` for exactly
+this reason ([`adr/0003`](../../../../adr/0003-instance-self-identification-and-version-pattern.md)).
+The example below is a conforming RFP Hub opportunity:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/The-RFP-Hub/the-rfp-hub/main/packages/standard/schemas/v1.0.0/opportunity.schema.json",
+  "@context": "https://raw.githubusercontent.com/The-RFP-Hub/the-rfp-hub/main/packages/standard/schemas/v1.0.0/context.jsonld",
+  "@type": "schema:Grant",
+  "specVersion": "1.0.0",
+  "id": "example:grant-1",
+  "fundingType": "grant",
+  "title": "Example Grants",
+  "description": "An example grant program, published as both plain JSON and linked data.",
+  "status": "open",
+  "sponsoringOrganizations": [{ "name": "Example Foundation" }],
+  "source": { "publisher": "example", "ingestedVia": "publisher_api" },
+  "applicationUrl": "https://example.org/grants/apply",
+  "deadlines": [
+    { "type": "fixed", "date": "2026-12-31T23:59:59.000Z", "label": "application" }
+  ],
+  "funding": { "currency": "USD", "budget": 250000 },
+  "grant": { "fundingMechanisms": ["retroactive", "matching"] }
+}
+```
+
+A JSON-LD processor expands this to a `schema:Grant` with `schema:identifier` / `schema:name` /
+`schema:description` / `schema:funder` / `schema:url`, with `budget` under
+`daoip5:totalGrantPoolSize` and `fundingMechanisms` under `daoip5:grantFundingMechanism`.
+
+Verify it yourself:
+
+```bash
+npx rfphub-validate that-document.json
+```
+
+*(The `$id` and `@context` hosts are placeholders pending the project domain decision — the
+documents they name are in this directory.)*