Data dictionary¶
Field-level contract for the employment schema and the interfaces that serve it. REST, DSL, and MCP read the same tables.
SFF Confidential
You agree to keep all Data strictly confidential and protect it with the same level of care you use to protect your own confidential information, but no less than reasonable care. Access to the Data is limited to your employees, contractors or agents who are informed of and agree to these confidentiality obligations. You are not permitted to disclose, distribute, publish, or otherwise share the Data, in any manner or medium, with any third party, without the prior written consent of the Foundation. You may not use the Data for commercial purposes.
Contents¶
- Core tables — company, occupation, wage, hiring, location
- TITLECONVERT — title matching tables and response fields
- Interfaces — table → REST / DSL / MCP
- Values — allowed values and join keys
Purpose¶
| Topic | Contract |
|---|---|
| This document | Field-level contract for the employment schema and the interfaces that serve it. All three interfaces read the same tables. |
| REST | HTTPS JSON at https://wywm.org (same app as https://aonav.ai). JWT on every data route. Resource URLs under /api/. |
| DSL | Query language posted to POST /api/dsl. Superset of REST. New capability lands here first. |
| MCP | POST /mcp, tool aoi_dsl_query. Every data query is a DSL command; there are no separate MCP resources per table. |
| Auth | JWT Bearer required. Role permissions gate REST vs DSL vs MCP and which data APIs a principal may call. |
How to read the schema¶
| Topic | Contract |
|---|---|
| Occupation grain | Callers consume cluster_id. Many O*NET codes share one cluster. Badges, wages, pathways, AI impact, and company–occupation hiring are cluster-keyed. TITLECONVERT de-duplicates at cluster_id. |
| Company grain | Canonical key is companies.company_name. company_uid is the stable identifier used in relationship lists. Pass names through COMPANYCONVERT before joining. |
| Title → occupation | TITLECONVERT (GET /api/titleconvert, DSL TITLECONVERT, MCP aoi_dsl_query). Do not map a job-title string to cluster_id yourself. |
| Location | ZIP → location_mapping → cbsa and msa_size. Wages and promotion filter on msa_size. Geographic hiring filters on cbsa / hiring_postings_qtile. |
| Null badges | NULL means insufficient data, not a low rating. |
| Column names | PostgreSQL columns are lowercase. REST JSON keeps company_URL. Filters listed on each field. |