ScopeSpec 0.1 — the normative field reference
Status: draft · First published 2026-09-10 · Last updated 2026-09-10 · Editor Ben Davis, ben.davis@bidbro.com · Licensed CC BY 4.0
In short
ScopeSpec is an open, versioned field list for a comparable residential project brief. It defines what a homeowner must state about a job, and what a contractor's quote must return, so that two quotes for the same project can be compared line for line instead of by headline price alone.
This version defines 40 fields across 9 groups, of which 31 are required, plus 15 fields a conforming quote returns, 10 enumerations, 6 trade profiles and 6 conformance rules. Every one of them is rendered below from the same file that generates the JSON Schema, so this page and the schema cannot disagree.
Status meaning. Published for public review and implementation. Field names and enumerations may change in 0.2; every 0.1 URL and artifact stays permanently available.
Conformance rules
| # | Rule | Why |
|---|---|---|
C1 | A conforming brief includes every field marked required in the core groups, and every field marked required by its declared trade profile. | A brief that omits a required field is not a ScopeSpec brief. It may still be a useful brief — the standard makes no claim about briefs outside it. |
C2 | Every quantity carries a unit and a measurementMethod. | A number without a stated unit and without how it was arrived at is the single most common cause of two quotes not being comparable. 'Roughly 1,800 square feet, paced off' and '1,812 square feet, from the plat' are both acceptable; a bare '1800' is not. |
C3 | Anything not stated as included is excluded, and the brief must say so explicitly in scope.exclusions. | The default direction matters. A brief silent on debris haul-away is read by one bidder as included and another as extra; the standard forces the question to be answered once, by the person writing the brief. |
C4 | An allowance is a stated budget for an undecided selection, and must carry an amount, a currency and what it covers. | An allowance without an amount is not an allowance, it is an unpriced hope. Bidders must be able to add identical allowances to identical base prices. |
C5 | A conforming quote states its priceBasis and repeats the brief's assumptions it accepts, listing separately any it restates. | This is what makes comparison possible at all. Two fixed prices against different assumption sets are two different jobs, and the restated assumptions are where that difference becomes visible. |
C6 | A brief carries no street address, no homeowner name, no telephone number and no email address. | Location is stated to postal-code granularity. A brief is a document that gets forwarded, so it is defined from the start to be safe to forward. Contact routing belongs to whatever platform carries the brief, not to the brief. |
The brief — 9 field groups
spec — Document identity
Says which version of the standard a reader is holding, so a brief written today is still interpretable when 0.2 exists.
| Field | Type | Required | Definition and example |
|---|---|---|---|
specVersion | string | required | The ScopeSpec version this brief conforms to. `0.1` for this version. Example: 0.1 |
briefId | string | required | An identifier unique within whoever issued the brief. Opaque; carries no personal information. Example: bb-2026-000412 |
created | date (YYYY-MM-DD) | required | ISO 8601 date the brief was first issued. Example: 2026-09-10 |
revision | integer | required | Increments every time the brief changes after it has been sent to anyone. Bidders quote a revision, not a brief. Example: 1 |
locale | string | optional | BCP 47 language tag for the prose fields. Example: en-US |
project — The project
What is being asked for, in the words of the person asking, plus the timing constraints that change a price.
| Field | Type | Required | Definition and example |
|---|---|---|---|
tradeProfile | one of: roofing-replacement, bathroom-remodel, kitchen-remodel, hvac-replacement, exterior-painting, other | required | The trade profile whose additional required fields apply. `other` is valid and imposes no extra fields. Example: roofing-replacement |
summary | string | required | One to three sentences describing the work in plain language. Not a specification — the fields below are the specification. Example: Replace the asphalt shingle roof on a two-storey house, including new underlayment and all flashing. |
motivation | string | optional | Why the work is being done. Changes what a good contractor proposes: an active leak and a planned sale lead to different recommendations. Example: Active leak over the back bedroom after the August storm. |
desiredStart | date (YYYY-MM-DD) | optional | Earliest acceptable start date, if there is one. Example: 2026-10-01 |
schedulingFlexibility | one of: urgent, firm-date, flexible, seasonal | required | How much the start date can move. A hard deadline is a price input and must not be discovered at contract stage. Example: flexible |
budgetStated | boolean | required | Whether the brief states a budget at all. Stating `false` is a legitimate and common answer. Example: false |
property — The property
The physical facts that change the work, at a granularity that cannot identify the household.
| Field | Type | Required | Definition and example |
|---|---|---|---|
propertyType | one of: single-family-detached, townhouse, condominium, duplex, manufactured, other | required | The kind of dwelling. Example: single-family-detached |
postalCode | string | required | Postal code only. Never a street address — see conformance rule C6. Example: 23451 |
locality | string | required | City or town name. Example: Virginia Beach |
region | string | required | State or province code. Example: VA |
yearBuilt | integer | optional | Year of original construction, if known. Drives code, material and hazard assumptions. Example: 1972 |
stories | integer | optional | Number of storeys above grade. An access and labour input on every exterior trade. Example: 2 |
occupiedDuringWork | boolean | required | Whether the household will be living in the property while the work runs. Changes sequencing, dust control and working hours. Example: true |
petsOnSite | boolean | optional | Whether animals will be present. A gate-and-containment question, not a courtesy field. Example: true |
scope — Scope — inclusions, exclusions, allowances
The heart of the standard. Comparability fails here more often than anywhere else, and it fails silently.
| Field | Type | Required | Definition and example |
|---|---|---|---|
inclusions | list of text | required | Every item of work the homeowner intends to be part of the price. One item per entry, written as a deliverable rather than a task. Example: ["Tear off existing shingles to deck", "Replace all step and valley flashing"] |
exclusions | list of text | required | Work explicitly NOT in the price. Required even when empty, because an empty exclusions list is itself a statement — see conformance rule C3. Example: ["Gutter replacement", "Interior ceiling repair"] |
allowances | list of allowance | required | Budgets for selections not yet made. Required even when empty. Example: [{"item": "Shingle upgrade to architectural", "amount": 1200, "currency": "USD", "covers": "material only"}] |
siteConditions | list of text | required | Known conditions a bidder would otherwise discover on site: soft decking, prior repairs, drainage, slope, known asbestos or lead, tight side yards. Example: ["Two areas of soft decking noted over the garage"] |
accessConstraints | list of text | required | Anything limiting how crews, materials or a dumpster reach the work. Required even when empty. Example: ["No driveway dumpster — HOA prohibits street placement"] |
debrisHandling | one of: homeowner, contractor, shared, undecided | required | Who removes and disposes of debris. The most commonly assumed-both-ways line item in residential work. Example: contractor |
cleanupStandard | one of: broom-clean, vacuumed, as-found, unstated | optional | The condition the site is returned in. Example: broom-clean |
measurements — Measurements
Quantities with units and provenance. A quantity whose origin is unstated cannot be checked, and an unchecked quantity is the usual reason two prices differ by a third.
| Field | Type | Required | Definition and example |
|---|---|---|---|
quantities | list of quantity | required | Each measurement the trade profile requires, plus any others that matter. Every entry carries name, value, unit, measurementMethod and confidence. Example: [{"name": "roofArea", "value": 2400, "unit": "sqft", "measurementMethod": "aerial-report", "confidence": "measured"}] |
quantitiesVerifiedBy | one of: homeowner, contractor, shared, undecided | required | Who is responsible for confirming the quantities before the price becomes binding. Example: contractor |
materials — Materials and selections
Whether the selections are made, who buys them, and what remains an allowance.
| Field | Type | Required | Definition and example |
|---|---|---|---|
selectionsComplete | boolean | required | Whether every material selection has been made. `false` is normal and must be paired with allowances. Example: false |
specifiedItems | list of specifiedItem | required | Items already chosen, named specifically enough to price. Required even when empty. Example: [{"item": "Shingle", "specification": "CertainTeed Landmark, Weathered Wood", "suppliedBy": "contractor"}] |
ownerSuppliedItems | list of text | required | Anything the homeowner will supply. Required even when empty — an unstated owner-supplied item is a schedule risk nobody priced. Example: [] |
permits — Permits and approvals
Permit assumptions stated up front, because a permit assumption discovered late moves both price and schedule.
| Field | Type | Required | Definition and example |
|---|---|---|---|
permitAssumedRequired | one of: yes, no, unknown | required | Whether the brief assumes a permit is required. `unknown` is an honest and common answer, and is treated as a question for the bidder rather than a defect. Example: yes |
permitPulledBy | one of: homeowner, contractor, shared, undecided | required | Who applies for and pays for the permit under this brief's assumptions. Example: contractor |
jurisdiction | string | optional | The permitting authority, where the homeowner knows it. Example: City of Virginia Beach Planning Department |
hoaApprovalRequired | one of: yes, no, unknown | required | Whether an HOA or architectural review approval is needed. Example: no |
inspectionsExpected | list of text | optional | Inspections the homeowner expects, where known. Example: ["Sheathing/nailing inspection", "Final"] |
documents — Photos and documents
What evidence accompanies the brief. A brief with no photographs is quoted more cautiously, and the caution is priced.
| Field | Type | Required | Definition and example |
|---|---|---|---|
photos | list of documentRef | required | Photographs supplied. Each entry states what the photo shows; a URL is optional and may be omitted for a brief that travels outside the issuing platform. Example: [{"documentType": "photo", "describes": "Rear elevation, full roof plane"}] |
drawings | list of documentRef | required | Plans, sketches or measured drawings. Required even when empty. Example: [] |
reports | list of documentRef | required | Inspection reports, engineer's letters, prior estimates being replaced. Required even when empty. Example: [{"documentType": "report", "describes": "2026 home inspection, roof section"}] |
assumptions — Stated assumptions
The list every bidder must accept or restate. This is the mechanism that converts a difference in reading into a visible difference on the page.
| Field | Type | Required | Definition and example |
|---|---|---|---|
assumptions | list of text | required | One assumption per entry, written so it can be accepted or contradicted without ambiguity. Example: ["Existing decking is sound except where noted in siteConditions", "Work proceeds in a single mobilisation"] |
The quote — what a conforming answer returns
The response half of the standard. A brief that does not say what a comparable answer looks like has only solved half the problem.
| Field | Type | Required | Definition and example |
|---|---|---|---|
priceBasis | one of: fixed-price, cost-plus, time-and-materials, not-to-exceed, allowance-based | required | How the price is constructed. Two prices on different bases are not comparable and must not be presented as if they were. Example: fixed-price |
priceTotal | number | required | The total for the scope as quoted, in the stated currency, exclusive of allowances listed separately. Example: 18400 |
currency | string | required | ISO 4217 currency code. Example: USD |
allowancesCarried | list of allowance | required | The brief's allowances as carried in this quote, so identical allowances sit on identical base prices. Example: [{"item": "Shingle upgrade to architectural", "amount": 1200, "currency": "USD", "covers": "material only"}] |
assumptionsAccepted | list of text | required | The brief's assumptions this quote accepts, verbatim. Example: ["Work proceeds in a single mobilisation"] |
assumptionsRestated | list of text | required | Assumptions the bidder replaced, with the replacement text. Required even when empty — this is where two apparently identical prices stop being identical. Example: ["Decking replacement priced at $4.50/sqft beyond the two noted areas"] |
exclusionsAdded | list of text | required | Anything the bidder excludes beyond the brief's own exclusions. Required even when empty. Example: [] |
validUntil | date (YYYY-MM-DD) | required | The date the price expires. A quote without an expiry cannot be compared against one with a short expiry on equal terms. Example: 2026-10-10 |
startWindow | string | required | When work could begin, as a stated window rather than a promise of a date. Example: Between 2026-10-06 and 2026-10-20 |
durationEstimate | string | required | Expected working duration, with the unit stated. Example: 3 working days, weather permitting |
paymentSchedule | list of text | required | Each payment as a stated trigger and amount or percentage. Example: ["25% at contract", "Balance on completion and final inspection"] |
warranty | string | required | Workmanship warranty in plain words, stated separately from any manufacturer warranty. Example: 5 years on workmanship; manufacturer covers material separately. |
changeOrderPolicy | string | required | How a change is priced and authorised. Unstated at quote stage, it is negotiated at the worst possible moment. Example: Written change order priced before work proceeds; no verbal changes. |
licenseNumber | string | optional | The contractor's licence number as issued by the relevant authority. Optional in the standard because licensing regimes differ; verification is the reader's responsibility, not the standard's. Example: 2705-XXXXXX |
insuranceOnFile | boolean | optional | Whether the bidder asserts current liability and workers' compensation cover. An assertion, not a verification — the standard never implies BidBro or anyone else has checked it. Example: true |
Trade profiles
A trade profile adds required measurements and a photo minimum to the core fields, and names the exclusions and allowances that go unstated most often in that trade. The lists of typical exclusions and allowances are guidance, not requirements — they exist because an omitted exclusion is the usual reason two prices are not comparable.
roofing-replacement — Roofing replacement
- Required quantities
roofAreapitchlayersExisting- Also required
property.stories- Minimum photographs
- 4
- Photo guidance
- One photograph of each elevation from ground level, plus a close view of any known problem area. Photograph flashing, valleys and penetrations where they can be reached safely — never climb to take a brief photograph.
- Commonly excluded
- Gutter replacement; Interior repair of water damage; Decking replacement beyond a stated quantity; Skylight replacement
- Commonly an allowance
- Decking replacement per sheet or per square foot; Shingle upgrade; Ventilation upgrade
bathroom-remodel — Bathroom remodel
- Required quantities
floorAreafixtureCount- Also required
property.yearBuiltmaterials.specifiedItems- Minimum photographs
- 4
- Photo guidance
- Each wall from the doorway, the floor, and the inside of the vanity cabinet showing the supply and waste connections. Photograph the ceiling if there is any staining.
- Commonly excluded
- Moving load-bearing walls; Window replacement; Repairs to concealed damage discovered on demolition
- Commonly an allowance
- Tile; Vanity and top; Fixtures and trim; Lighting
kitchen-remodel — Kitchen remodel
- Required quantities
floorArealinearFeetCabinetry- Also required
property.yearBuiltmaterials.specifiedItemsmaterials.ownerSuppliedItems- Minimum photographs
- 5
- Photo guidance
- Each wall, the floor, the ceiling, and the panel or breaker serving the kitchen. Include a photograph taken from the adjoining room through the doorway — access for cabinetry is a real constraint.
- Commonly excluded
- Appliance supply; Structural alterations; Asbestos or lead abatement; Flooring beyond the kitchen footprint
- Commonly an allowance
- Countertop; Cabinetry; Appliances; Backsplash tile; Plumbing fixtures
hvac-replacement — HVAC replacement
- Required quantities
conditionedAreaexistingSystemAge- Also required
property.yearBuiltproperty.stories- Minimum photographs
- 3
- Photo guidance
- The outdoor unit including its data plate, the indoor air handler or furnace including its data plate, and the thermostat. A legible data plate answers more questions than any description.
- Commonly excluded
- Duct replacement or resizing; Electrical service upgrade; Drywall repair after equipment access; Permit fees where stated as homeowner-pulled
- Commonly an allowance
- Duct modification; Line-set replacement; Condensate pump or drain rework
exterior-painting — Exterior painting
- Required quantities
paintableAreastories- Also required
property.yearBuiltscope.siteConditions- Minimum photographs
- 4
- Photo guidance
- Each elevation, plus close views of any peeling, rot or previous repair. A pre-1978 property should include a photograph of a representative painted surface, because lead-safe practices are a price input.
- Commonly excluded
- Carpentry repair beyond a stated quantity; Window glazing; Roof or gutter painting; Pressure washing of hard surfaces
- Commonly an allowance
- Carpentry repair per linear or square foot; Additional coat; Trim colour change
other — Other work
- Required quantities
- None beyond the core fields.
- Also required
- Nothing beyond the core required fields.
- Minimum photographs
- 2
- Photo guidance
- At minimum, a wide view establishing where the work is and a close view of the specific condition being addressed.
- Commonly excluded
- —
- Commonly an allowance
- —
Enumerations
| Identifier | Name | Values |
|---|---|---|
tradeProfile | Trade profile | roofing-replacement bathroom-remodel kitchen-remodel hvac-replacement exterior-painting other |
propertyType | Property type | single-family-detached townhouse condominium duplex manufactured other |
schedulingFlexibility | Scheduling flexibility | urgent firm-date flexible seasonal |
responsibility | Responsibility | homeowner contractor shared undecided |
priceBasis | Price basis | fixed-price cost-plus time-and-materials not-to-exceed allowance-based |
measurementMethod | Measurement method | tape-measured laser-measured aerial-report from-drawings estimated unknown |
confidence | Quantity confidence | measured approximate rough |
cleanupStandard | Cleanup standard | broom-clean vacuumed as-found unstated |
tristate | Yes / no / unknown | yes no unknown |
documentType | Document type | photo drawing report prior-estimate other |
Machine-readable artifacts
The schema is JSON Schema draft-07, chosen because it is what a validator in this repository can actually run — a schema nobody can execute is a decorative schema. The citation file follows Citation File Format 1.2.0.
- JSON Schema (draft-07) — scopespec-0.1.schema.jsonValidates a brief. The quote half is at #/definitions/scopeSpecQuote in the same file.
- Field registry — scopespec-0.1.jsonEverything on this page as data: groups, fields, enumerations, trade profiles and limitations.
- Worked example — roofing replacement briefA conforming brief. Illustrative only: no real property, household or contractor.
- Worked example — bathroom remodel briefA conforming brief for an interior trade, with three allowances and incomplete selections.
- Worked example — a conforming quoteThe response half against the roofing brief, including one restated assumption.
- CITATION.cffCitation metadata in Citation File Format 1.2.0.
Limitations — what this standard does not do
- ScopeSpec describes a project; it does not price one. Nothing in it produces, implies or validates a cost.
- The six trade profiles in 0.1 are the trades BidBro can describe carefully today. They are not a claim about which trades matter most, and the standard is explicitly incomplete outside them — use `other`, which imposes no extra fields, rather than forcing a job into a profile that does not fit.
- Field names and enumerations may change in 0.2. Every 0.1 URL and artifact remains available permanently so a brief written against 0.1 stays interpretable.
- The standard asserts nothing about licensing, insurance or competence. `licenseNumber` and `insuranceOnFile` record what a bidder states; verifying either is the reader's responsibility.
- No adoption is claimed. As of the published date, BidBro knows of no third-party implementation, and this page will name implementers only when they exist and agree to be named.
How to cite this version
BidBro, Inc. (2026). ScopeSpec 0.1: a comparable residential project brief. https://www.bidbro.com/scopespec/v0-1 (CC BY 4.0)
ScopeSpec is published under CC BY 4.0: implement it, extend it, or fork it, with credit in plain text. A link back is welcome and is never required.
Version history
- 0.1 — 2026-09-10. First public version. Nine core field groups, ten enumerations, six trade profiles and six conformance rules, with a JSON Schema, a machine-readable field registry, two worked examples and a CITATION.cff.
- This URL is permanent. When 0.2 is published it gets its own page and this one stays exactly as it is, apart from dated corrections recorded in this list.
Corrections
If a field definition here is wrong, ambiguous, or disagrees with the published schema, email ben.davis@bidbro.com. Corrections are dated in the version history above rather than made silently.
Elsewhere on BidBro
- Virginia Beach contractors — licensed contractors by trade across the city.
- Virginia home-improvement projects — live projects taking bids.
- Hampton Roads Home Project Observatory — BidBro’s published construction data, methodology and citation terms.
- Press kit and reporter data desk — company facts and a named press contact.