markform 0.1.7 → 0.1.9

package/docs/markform-reference.md

@@ -56,7 +56,7 @@ They are Markdoc syntax, which is a superset of Markdown.
 ## Field Kinds
 
 Markform uses the term **field kind** to refer to the type of a field (e.g., `string`,
-`number`, `checkboxes`). The term **data type** refers to the underlying value
+`number`, `checkboxes`, `table`). The term **data type** refers to the underlying value
 representation. See the Type System section in SPEC.md for full details.
 
 ### String Field
@@ -263,19 +263,72 @@ Integer year with optional constraints.
 2015
 `````
 {% /field %}
-````
+`````
 
 | Attribute | Type | Description |
 |-----------|------|-------------|
 | `min` | number | Minimum year (inclusive) |
 | `max` | number | Maximum year (inclusive) |
 
+### Table Field
+
+Structured tabular data with typed columns. Uses standard markdown table syntax.
+
+````markdown
+{% field kind="table" id="team" label="Team Members" required=true
+   columnIds=["name", "title", "start_date"]
+   columnLabels=["Name", "Job Title", "Start Date"]
+   columnTypes=["string", "string", "date"]
+   minRows=1 maxRows=20 %}
+| Name | Job Title | Start Date |
+|------|-----------|------------|
+| Alice Smith | Engineer | 2023-01-15 |
+| Bob Jones | Designer | 2022-06-01 |
+{% /field %}
+`````
+
+**Basic table (columnLabels backfilled from header row):**
+
+```markdown
+{% field kind="table" id="items" label="Items"
+   columnIds=["name", "quantity", "price"] %}
+| Name | Quantity | Price |
+|------|----------|-------|
+{% /field %}
+```
+
+| Attribute | Type | Required | Description |
+| --- | --- | --- | --- |
+| `columnIds` | string[] | Yes | Array of snake_case column identifiers |
+| `columnLabels` | string[] | No | Display labels (defaults to header row) |
+| `columnTypes` | string[] | No | Column types (defaults to all `string`) |
+| `minRows` | number | No | Minimum row count (default: 0) |
+| `maxRows` | number | No | Maximum row count (default: unlimited) |
+
+**Column types:**
+
+| Type | Description | Validation |
+| --- | --- | --- |
+| `string` | Any text value | None |
+| `number` | Numeric value | Integer or float |
+| `url` | URL value | Valid URL format |
+| `date` | Date value | ISO 8601 (YYYY-MM-DD) |
+| `year` | Year value | Integer (1000-9999) |
+
+**Sentinel values in cells:** Use `%SKIP%` or `%ABORT%` with optional reasons:
+
+```markdown
+| 2017 | I, Tonya | 90 | %SKIP% (Not tracked) |
+```
+
+**Cell escaping:** Use `\|` for literal pipe characters in cell values.
+
 ## Common Attributes
 
 All fields support these attributes:
 
 | Attribute | Type | Default | Description |
-|-----------|------|---------|-------------|
+| --- | --- | --- | --- |
 | `id` | string | required | Unique snake_case identifier |
 | `label` | string | required | Human-readable label |
 | `required` | boolean | false | Must be filled for completion |
@@ -285,7 +338,7 @@ All fields support these attributes:
 **Text-entry fields only** (string, number, string-list, url, url-list):
 
 | Attribute | Type | Description |
-|-----------|------|-------------|
+| --- | --- | --- |
 | `placeholder` | string | Hint text shown in empty fields |
 | `examples` | string[] | Example values (helps LLMs understand expected format) |
 
@@ -294,7 +347,8 @@ All fields support these attributes:
 {% field kind="number" id="revenue" label="Revenue" placeholder="1000000" examples=["500000", "1000000"] %}{% /field %}
 ```
 
-Note: `placeholder` and `examples` are NOT valid on chooser fields (single-select, multi-select, checkboxes).
+Note: `placeholder` and `examples` are NOT valid on chooser fields (single-select,
+multi-select, checkboxes).
 
 ## Documentation Blocks
 
@@ -316,7 +370,7 @@ Additional context or caveats.
 {% examples ref="field_id" %}
 Example values: "AAPL", "GOOGL", "MSFT"
 {% /examples %}
-````
+```
 
 Place doc blocks after the element they reference.
 
@@ -549,6 +603,11 @@ markform export form.md --format=json    # Export values as JSON
 markform export form.md --format=yaml    # Export values as YAML
 markform export form.md --format=markdown  # Readable markdown (strips tags)
 
+# Export form structure as JSON Schema
+markform schema form.md                  # Full schema with x-markform extensions
+markform schema form.md --pure           # Pure JSON Schema (no extensions)
+markform schema form.md --draft draft-07 # Specify draft version
+
 # Other commands
 markform serve form.md       # Web UI for browsing
 markform examples            # Try built-in examples

package/docs/markform-spec.md

@@ -1385,12 +1385,12 @@ type IssueReason =
   | 'checkbox_incomplete'    // Required checkboxes with non-terminal states
   | 'min_items_not_met'      // String-list or multi-select below minimum
   // Severity: *recommended* (optional improvements)
-  | 'optional_empty';        // Optional field with no value
+  | 'optional_unanswered';   // Optional field not yet addressed
 
 // Mapping from ValidationIssue to InspectIssue:
 // - ValidationIssue.severity='error' → InspectIssue.severity='required'
 // - ValidationIssue.severity='warning'/'info' → InspectIssue.severity='recommended'
-// - Missing optional fields → severity='recommended', reason='optional_empty'
+// - Unanswered optional fields → severity='recommended', reason='optional_unanswered'
 ```
 
 #### StructureSummary and ProgressSummary
@@ -2695,7 +2695,7 @@ type.
 | `checkbox_incomplete` | 3 (required) / 2 (recommended) |
 | `validation_error` | 2 |
 | `min_items_not_met` | 2 |
-| `optional_empty` | 1 |
+| `optional_unanswered` | 1 |
 
 **Total Score** = Field Priority Weight + Issue Type Score
 

package/examples/movie-research/{movie-research-deep.form.md → movie-deep-research.form.md}

@@ -1,7 +1,7 @@
 ---
 markform:
   spec: MF/0.1
-  title: Movie Research (Deep)
+  title: Movie Deep Research
   description: Comprehensive movie research form with ratings, box office, cast/crew, technical specs, streaming availability, and cultural analysis.
   run_mode: research
   roles:
@@ -40,7 +40,7 @@ markform:
     max_patches_per_turn: 15
 ---
 
-{% form id="movie_research_deep" title="Movie Research (Deep)" %}
+{% form id="movie_research_deep" title="Movie Deep Research" %}
 
 {% description ref="movie_research_deep" %}
 Comprehensive movie research covering ratings from multiple sources, box office performance, full cast and crew, technical specifications, streaming availability, and cultural impact analysis.
@@ -249,72 +249,31 @@ Example: "Emma Thomas (producer)"
 
 ## Ratings
 
-{% group id="imdb_ratings" title="IMDB Ratings" %}
+{% group id="ratings" title="Ratings" %}
 
-{% field kind="number" id="imdb_rating" label="IMDB Rating" role="agent" min=1.0 max=10.0 %}{% /field %}
-
-{% instructions ref="imdb_rating" %}
-IMDB user rating (1.0-10.0 scale).
-{% /instructions %}
-
-{% field kind="number" id="imdb_votes" label="IMDB Vote Count" role="agent" min=0 %}{% /field %}
-
-{% instructions ref="imdb_votes" %}
-Number of IMDB user votes (e.g., 2800000 for a popular film).
-{% /instructions %}
-
-{% /group %}
-
-{% group id="rotten_tomatoes_ratings" title="Rotten Tomatoes Ratings" %}
-
-{% field kind="number" id="rt_critics_score" label="Tomatometer (Critics)" role="agent" min=0 max=100 %}{% /field %}
-
-{% instructions ref="rt_critics_score" %}
-Tomatometer percentage (0-100).
-{% /instructions %}
-
-{% field kind="number" id="rt_critics_count" label="Critics Review Count" role="agent" min=0 %}{% /field %}
-
-{% field kind="number" id="rt_audience_score" label="Audience Score" role="agent" min=0 max=100 %}{% /field %}
-
-{% instructions ref="rt_audience_score" %}
-Audience Score percentage (0-100).
+{% field kind="table" id="ratings_table" label="Ratings" role="agent" required=true
+   columnIds=["source", "score", "votes"] columnTypes=["string", "number", "number"]
+   minRows=0 maxRows=6 %}
+| Source | Score | Votes |
+|--------|-------|-------|
+{% /field %}
+{% instructions ref="ratings_table" %}
+Fill in scores and vote/review counts from each source:
+- IMDB: Rating (1.0-10.0 scale), vote count
+- RT Critics: Tomatometer (0-100%), review count
+- RT Audience: Audience Score (0-100%), rating count
+- Metacritic: Metascore (0-100)
+- Letterboxd: Rating (0.5-5.0 scale)
+- CinemaScore: Grade (A+ to F), leave votes empty
 {% /instructions %}
 
 {% field kind="string" id="rt_consensus" label="Critics Consensus" role="agent" maxLength=500 %}{% /field %}
-
 {% instructions ref="rt_consensus" %}
 The official Rotten Tomatoes critics consensus statement, if available.
 {% /instructions %}
 
 {% /group %}
 
-{% group id="metacritic_ratings" title="Metacritic Ratings" %}
-
-{% field kind="number" id="metacritic_score" label="Metacritic Score" role="agent" min=0 max=100 %}{% /field %}
-
-{% instructions ref="metacritic_score" %}
-Metascore (0-100 scale). Leave empty if not available.
-{% /instructions %}
-
-{% /group %}
-
-{% group id="additional_ratings" title="Additional Ratings" %}
-
-{% field kind="number" id="letterboxd_rating" label="Letterboxd Rating" role="agent" min=0.5 max=5.0 %}{% /field %}
-
-{% instructions ref="letterboxd_rating" %}
-Letterboxd average rating (0.5-5.0 scale, in 0.1 increments).
-{% /instructions %}
-
-{% field kind="string" id="cinemascore" label="CinemaScore Grade" role="agent" pattern="^[A-F][+-]?$" %}{% /field %}
-
-{% instructions ref="cinemascore" %}
-Opening weekend audience grade (A+ to F). Only available for theatrical releases.
-{% /instructions %}
-
-{% /group %}
-
 ## Box Office
 
 {% group id="box_office" title="Box Office" %}

package/examples/movie-research/movie-research-demo.form.md

@@ -1,8 +1,8 @@
 ---
 markform:
   spec: MF/0.1
-  title: Movie Research (Demo)
-  description: Quick movie lookup with just the essentials (title, year, ratings, summary).
+  title: Movie Research Demo
+  description: Movie lookup with ratings from IMDB and Rotten Tomatoes.
   run_mode: research
   roles:
     - user
@@ -10,42 +10,28 @@ markform:
   role_instructions:
     user: "Enter the movie title."
     agent: |
-      Quickly identify the movie and fill in basic info from IMDB.
-      This is a demo lookup - just get the core facts.
----
-{% form id="movie_research_demo" title="Movie Research (Demo)" %}
+      Identify the movie with web searches and use imdb.com and rottentomatoes.com to fill in the ratings.
 
-## Movie Research Example
+---
+{% form id="movie_research_demo" %}
 
-{% group id="movie_input" title="Movie Identification" %}
+{% group id="movie_input" %}
 
-What movie do you want to research? \[*This field is filled in by the user (`role="user"`).*\]
+## What movie do you want to research?
 
 {% field kind="string" id="movie" label="Movie" role="user" required=true minLength=1 maxLength=300 %}{% /field %}
+
 {% instructions ref="movie" %}Enter the movie title (add year or details for disambiguation).{% /instructions %}
 
 {% /group %}
 
-## About the Movie
-
 {% group id="about_the_movie" title="About the Movie" %}
 
-**Title:**
-
-{% field kind="string" id="full_title" label="Full Title" role="agent" required=true %}{% /field %}
-{% instructions ref="full_title" %}Official title, including subtitle if any.{% /instructions %}
-
-**Release year:**
+## Movie Ratings
 
-{% field kind="number" id="year" label="Release Year" role="agent" required=true min=1888 max=2030 %}{% /field %}
+Here are the ratings for the movie:
 
-**IMDB:**
-
-{% field kind="url" id="imdb_url" label="IMDB URL" role="agent" required=true %}{% /field %}
-
-**MPAA rating:**
-
-{% field kind="single_select" id="mpaa_rating" label="MPAA Rating" role="agent" %}
+{% field kind="single_select" id="mpaa_rating" role="agent" label="MPAA Rating" %}
 - [ ] G {% #g %}
 - [ ] PG {% #pg %}
 - [ ] PG-13 {% #pg_13 %}
@@ -54,16 +40,21 @@ What movie do you want to research? \[*This field is filled in by the user (`rol
 - [ ] NR/Unrated {% #nr %}
 {% /field %}
 
-**IMDB rating:**
-
-{% field kind="number" id="imdb_rating" label="IMDB Rating" role="agent" min=1.0 max=10.0 %}{% /field %}
-{% instructions ref="imdb_rating" %}IMDB user rating (1.0-10.0 scale).{% /instructions %}
-
-**Summary:**
+{% field kind="table" id="ratings_table" role="agent"
+   label="Ratings" required=true
+   columnIds=["source", "score", "votes"] columnTypes=["string", "number", "number"]
+   minRows=0 maxRows=3 %}
+| Source | Score | Votes |
+|--------|-------|-------|
+{% /field %}
 
-{% field kind="string" id="logline" label="One-Line Summary" role="agent" maxLength=300 %}{% /field %}
-{% instructions ref="logline" %}Brief plot summary in 1-2 sentences, no spoilers.{% /instructions %}
+{% instructions ref="ratings_table" %}
+Fill in scores and vote counts from each source:
+- IMDB: Rating (1.0-10.0 scale), vote count
+- RT Critics: Tomatometer (0-100%), review count
+- RT Audience: Audience Score (0-100%), rating count
+{% /instructions %}
 
 {% /group %}
 
-{% /form %}
+{% /form %}

package/examples/rejection-test/rejection-test-mock-filled.form.md

@@ -0,0 +1,41 @@
+---
+markform:
+  spec: MF/0.1
+  title: Rejection Test Form
+  description: "Tests type mismatch rejection and recovery behavior"
+  roles:
+    - agent
+---
+
+{% form id="rejection_test" title="Rejection Test Form" %}
+
+{% description ref="rejection_test" %}
+A form to test patch rejection scenarios - verifies that type mismatch
+errors are properly recorded and recovery works.
+{% /description %}
+
+{% group id="fields" title="Test Fields" %}
+
+{% field kind="table" id="ratings" label="Ratings" required=true minRows=1 maxRows=5
+   columnIds=["source", "score", "votes"]
+   columnLabels=["Source", "Score", "Votes"]
+   columnTypes=["string", "number", "number"] %}
+| Source | Score | Votes |
+|--------|-------|-------|
+| IMDB | 85 | 12500 |
+| Rotten Tomatoes | 92 | 450 |
+{% /field %}
+
+{% instructions ref="ratings" %}
+Enter rating data with source name, score (0-100), and vote count.
+{% /instructions %}
+
+{% field kind="string" id="title" label="Title" required=true %}
+```value
+Test Movie
+```
+{% /field %}
+
+{% /group %}
+
+{% /form %}

package/examples/rejection-test/rejection-test-mock-filled.report.md

@@ -0,0 +1,15 @@
+# Rejection Test Form
+
+A form to test patch rejection scenarios - verifies that type mismatch
+errors are properly recorded and recovery works.
+
+## Test Fields
+
+**Ratings:**
+| Source | Score | Votes |
+| --- | --- | --- |
+| IMDB | 85 | 12500 |
+| Rotten Tomatoes | 92 | 450 |
+
+**Title:**
+Test Movie

package/examples/rejection-test/rejection-test-mock-filled.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "rejection_test",
+  "type": "object",
+  "properties": {
+    "ratings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "source": {
+            "title": "Source",
+            "type": "string"
+          },
+          "score": {
+            "title": "Score",
+            "type": "number"
+          },
+          "votes": {
+            "title": "Votes",
+            "type": "number"
+          }
+        }
+      },
+      "title": "Ratings",
+      "minItems": 1,
+      "maxItems": 5,
+      "x-markform": {
+        "role": "agent",
+        "group": "fields"
+      }
+    },
+    "title": {
+      "type": "string",
+      "title": "Title",
+      "x-markform": {
+        "role": "agent",
+        "group": "fields"
+      }
+    }
+  },
+  "title": "Rejection Test Form",
+  "description": "A form to test patch rejection scenarios - verifies that type mismatch\nerrors are properly recorded and recovery works.",
+  "required": ["ratings", "title"],
+  "x-markform": {
+    "spec": "MF/0.1",
+    "roles": ["user", "agent"],
+    "roleInstructions": {
+      "user": "Fill in the fields you have direct knowledge of.",
+      "agent": "Complete the remaining fields based on the provided context."
+    },
+    "groups": [
+      {
+        "id": "fields",
+        "title": "Test Fields"
+      }
+    ]
+  }
+}

package/examples/rejection-test/rejection-test-mock-filled.yml

@@ -0,0 +1,13 @@
+values:
+  ratings:
+    state: answered
+    value:
+      - source: IMDB
+        score: 85
+        votes: 12500
+      - source: Rotten Tomatoes
+        score: 92
+        votes: 450
+  title:
+    state: answered
+    value: Test Movie

package/examples/rejection-test/rejection-test.form.md

@@ -0,0 +1,35 @@
+---
+markform:
+  spec: MF/0.1
+  title: Rejection Test Form
+  description: "Tests type mismatch rejection and recovery behavior"
+  roles:
+    - agent
+---
+
+{% form id="rejection_test" title="Rejection Test Form" %}
+
+{% description ref="rejection_test" %}
+A form to test patch rejection scenarios - verifies that type mismatch
+errors are properly recorded and recovery works.
+{% /description %}
+
+{% group id="fields" title="Test Fields" %}
+
+{% field kind="table" id="ratings" label="Ratings" required=true minRows=1 maxRows=5
+   columnIds=["source", "score", "votes"]
+   columnLabels=["Source", "Score", "Votes"]
+   columnTypes=["string", "number", "number"] %}
+| Source | Score | Votes |
+|--------|-------|-------|
+{% /field %}
+
+{% instructions ref="ratings" %}
+Enter rating data with source name, score (0-100), and vote count.
+{% /instructions %}
+
+{% field kind="string" id="title" label="Title" required=true %}{% /field %}
+
+{% /group %}
+
+{% /form %}