<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Alastair Parker on Medium]]></title>
        <description><![CDATA[Stories by Alastair Parker on Medium]]></description>
        <link>https://medium.com/@jargon-sh?source=rss-88c101c5f802------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*vOEkbZuaDH0LNipOixU_KQ@2x.jpeg</url>
            <title>Stories by Alastair Parker on Medium</title>
            <link>https://medium.com/@jargon-sh?source=rss-88c101c5f802------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 19:31:32 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@jargon-sh/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Your Data Model Has No Package Manager]]></title>
            <link>https://jargon-sh.medium.com/your-data-model-has-no-package-manager-5b02dbb7a350?source=rss-88c101c5f802------2</link>
            <guid isPermaLink="false">https://medium.com/p/5b02dbb7a350</guid>
            <category><![CDATA[data-governance]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[software-architecture]]></category>
            <dc:creator><![CDATA[Alastair Parker]]></dc:creator>
            <pubDate>Tue, 08 Sep 2026 22:31:20 GMT</pubDate>
            <atom:updated>2026-09-08T22:31:20.805Z</atom:updated>
            <content:encoded><![CDATA[<h4>What Log4j taught software about dependencies — and why information models never got the memo.</h4><p>December 2021. A logging library nobody thought twice about gets a CVE score of 10.0. Log4Shell wasn’t just a bad bug. It was a mirror — it showed the industry something most people didn’t want to admit: nobody actually knew what was inside their own systems.</p><p>Log4j wasn’t obscure. It was buried three, four, five layers deep in dependency trees, pulled in by a library that pulled in another library that someone added two years earlier to solve a completely different problem. Patching it took an afternoon. Finding every place it lived took weeks. And the process looked the same everywhere: does anyone know if we use this? Anyone? How would we even check?</p><p>Code eventually got an answer, because code has package managers. Most information models — the concepts and definitions the code is actually built on — still don’t.</p><h3>The instinct, and why it misses</h3><p>When something like this happens, the instinct is to reach for governance. Get everyone in a room. Agree on standards. Set up a review board. Put someone in charge of approving what goes into production.</p><p>That’s not what fixed Log4j. Committees didn’t fix Log4j. Traceability did — SBOMs, lockfiles, dependency trees, scanners that could answer one question fast: does this exist in our stack, where, and at what version?</p><p>A review board was never going to help either, because a review board isn’t why anyone picked up Log4j in the first place. Developers pulled it in because it solved a problem — good logging, fast — not because a governance process signed off on it. Nobody adopting an open-source library checks its internals or its politics. They’re solving a problem and moving on. Add a gate upstream and you haven’t fixed anything; you’ve just made the thing people already skip a bit slower to skip.</p><p>The organisations that recovered fast weren’t the ones with the tightest change-control process. They were the ones who could already answer “who’s on version X, and what do they need to move to” — without three weeks digging through build files. The ones who struggled weren’t reckless. They were blind. Nothing in their toolchain made “I import this, which imports that, which imports Log4j 2.14” visible.</p><p>That traceability didn’t come from nowhere, though. It only worked because something upstream was already true: the dependency had been declared. A package manager forces every layer to name itself, version itself, register itself — long before anyone needs to trace anything. The SBOM is downstream of the package manager. You can’t scan your way to a graph that was never built as a graph.</p><h3>The same problem, minus the package manager</h3><p>This is the exact shape of problem Jargon exists for. Same mechanics, different substance — concepts instead of code, slower consequences than a CVE, no less real.</p><p>Picture any large federated effort to define shared vocabulary: standards bodies, industry consortia, cross-agency data models, whatever the domain. Multiple working groups. None fully in charge of the others. All building on shared foundational concepts nobody owns outright.</p><p>That’s a dependency graph. It just doesn’t look like one, because nothing forces it to be declared as one. It lives in PDFs, spreadsheets, tribal knowledge, and good intentions.</p><p>Here’s a real one. Not a mockup built to make a point — the actual graph produced when a real federated standards effort modelled its vocabulary in Jargon:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*F4fBSabKFOYBDQvwHQdasw.jpeg" /></figure><p>Every arc is a real, versioned import — one domain relying on another’s definition of something. Nobody drew this by hand. It’s what falls out automatically once dependencies are declared instead of assumed.</p><p>Now say one of those foundational domains gets corrected. A cardinality that was wrong. A code list that was too loose. A type that should always have been a reference and wasn’t. Nothing pages anyone. No CVE, no severity score, no security team getting woken at 2am. The fix just sits there, quietly right, while three working groups away someone’s still building on the old, wrong shape — because nobody told them the ground had moved.</p><p>That’s Log4j without the alarm bells. Nobody did anything wrong. Two teams built on the same concept, one moved to the corrected version, the other didn’t know, and eighteen months later two “conformant” outputs turn out not to talk to each other.</p><p>So here’s the obvious question: why don’t information models get the same treatment as code? Nobody would seriously track software dependencies through changelog PDFs and hallway conversations — we settled that in the 2000s. But that’s still exactly how most standards and shared data models work. Definitions live in documents. “Who’s using what version” is a question you answer by asking around. The only thing stopping silent drift is people happening to talk to each other.</p><h3>What a package manager for concepts actually needs</h3><p>This is why the fix isn’t a scanner bolted on after the fact — that’s the SBOM approach, and SBOMs only work because something upstream already declared the dependencies properly. What’s missing for information models is that upstream layer, and it has to do three things at once:</p><ul><li><strong>Be a package manager for concepts.</strong> Domains declared, versioned with real semver, imported explicitly — the same discipline npm or Maven bring to code, just applied to definitions.</li><li><strong>Be somewhere to publish, not just consume.</strong> Teams aren’t only importing someone else’s domain. They’re authoring and releasing their own, the way you’d publish a package, not just install one.</li><li><strong>Carry governance on top of that</strong> — the part general-purpose package managers famously skip. Npm tells you what depends on what. It won’t tell you who’s allowed to change it, or what “correct” even means for a given domain. And that governance layer only holds up if it’s executable, wired into the same workflow the modelling happens in, so the blast radius gets computed automatically instead of relying on someone remembering to check. A governance policy sitting in a document nobody opens isn’t governance. It’s a PDF with opinions.</li></ul><p>The graph above is what you get once all three are true at once — not a diagram built to make a point, the automatic byproduct of dependencies declared on purpose.</p><h3>Guardrails, not gates</h3><p>In a genuinely federated effort, there’s no single body with authority over the whole graph — that’s the point of it being federated. Get everyone in a room and govern it properly was never going to scale here any better than it did for Log4j. There’s no room big enough, and no single owner to put in charge of concepts a dozen independent groups all depend on.</p><p>That doesn’t make governance the wrong goal. It makes the committee the wrong mechanism. Governance’s actual job is making the impact of a change visible before it ships, not deciding whether it’s allowed to ship at all. That’s what the image above does: for anyone, any time — if this changes, here’s its blast radius. Not a policy that says changes need sign-off. A graph you can query, wired straight into the pipeline the work already runs through.</p><p>Governance that isn’t automated, that doesn’t live in that pipeline, doesn’t scale in a federated system. It just becomes another meeting nobody has time for. Guardrails, not gates — checked automatically, blast radius computed automatically, owners notified automatically. That’s the version that actually keeps up.</p><h3>Where this is heading</h3><p>Log4j happened because humans, moving fast, pulled in dependencies without checking where they came from. That’s the default behaviour of an AI agent generating an artefact today: reach for whatever shape looks plausible, faster than any human, with even less instinct to check provenance. The federated-standards version of Log4j took years to compound quietly. An ungoverned agent could do the same thing in an afternoon, across everything it touches — which is exactly why the traceability needs to be built in at generation time, not bolted on after something’s already broken.</p><h3>This isn’t a five-minute fix. That’s fine.</h3><p>None of this is a trial you spin up and walk away converted in five minutes. Neither was CI/CD. Neither was DevOps. Nobody adopted those because a demo blew their mind — they got adopted because a team applied the discipline to one pipeline, then another, until it was just how the place worked.</p><p>A package manager for your concepts is the same kind of shift. It pays off as a practice, not a feature you flip on.</p><p>So the honest starting point isn’t “sign up and see.” It’s smaller than that: pick the one domain causing you the most pain right now — the one three teams already argue about — and model it properly. Version it. Let other teams import it instead of redefining it from scratch. See what the graph actually looks like once that one piece is declared instead of assumed.</p><p>That’s <a href="https://jargon.sh/">jargon.sh</a>. And it costs nothing to start — modelling and using domains solo is free. You only pay once you need the collaborative version: a team working off the same governed source, or an agent pulling from it through the MCP server. Which, if you think about it, is the right order anyway. Prove the discipline yourself first, on the thing costing you the most today, before you need anyone — or anything — else to trust it too.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5b02dbb7a350" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your AI agent is guessing. It shouldn’t have to.]]></title>
            <link>https://jargon-sh.medium.com/your-ai-agent-is-guessing-it-shouldnt-have-to-49dee04eda7c?source=rss-88c101c5f802------2</link>
            <guid isPermaLink="false">https://medium.com/p/49dee04eda7c</guid>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <dc:creator><![CDATA[Alastair Parker]]></dc:creator>
            <pubDate>Mon, 07 Sep 2026 04:00:21 GMT</pubDate>
            <atom:updated>2026-09-07T04:00:21.221Z</atom:updated>
            <content:encoded><![CDATA[<p>Here’s an honest confession before we start: if you’re one team, in one repo, with a decent type system and a well-maintained spec file checked into git, you probably don’t need what’s below. Your compiler already catches most of the dumb mistakes. An agent working in that repo already has a source of truth sitting right there.</p><p>This isn’t about that case.</p><p>Jargon is a platform for designing a shared model of a business concept: its shape, its valid states, what’s allowed to happen to it — once, in one place, so anything downstream can read it instead of reinventing it.</p><p>AI coding agents read that model over MCP (Model Context Protocol — the standard way agents pull in outside context they weren’t trained on). That’s the part this post is actually about: not spec-driven development in general, which is already well covered elsewhere, but the one layer underneath it — the domain model — that most teams still leave unwritten.</p><h3>Where it actually breaks</h3><p>A Café runs an Order through a lifecycle: Placed, then Preparing once it&#39;s paid for, then Ready, then Completed once it&#39;s collected. The only way out early is Cancelled — and that&#39;s only reachable from Placed. Once the barista&#39;s started on it, that door&#39;s closed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*y_Nv2Tos7rEvB0v8SYJmRQ.png" /></figure><p>Now suppose Payments is a separate service, owned by a separate team, that has to call in and confirm payment against that order. Payments doesn’t own the Order lifecycle. It just needs to know, correctly, that it&#39;s only safe to trigger payment while the order is still Placed — never once it&#39;s Preparing, Ready, or Completed, or you&#39;ve just double-charged someone, or accepted a payment for an order that&#39;s already being made.</p><p>Both teams already agree on this, informally, today. Someone explained it in a design doc eighteen months ago, or a Slack thread, or a diagram pinned to a wiki page nobody’s opened since. The Order team can change that lifecycle next sprint — add a state, rename a transition — and nothing requires them to tell Payments, because nothing connects the two beyond memory and goodwill.</p><p>This is the case Jargon is for. Not “an agent might guess wrong inside your own repo” — that’s usually survivable. It’s “two things, owned by different people, have to agree on a concept neither of them fully controls, without a shared PR review to catch drift.”</p><p>Here’s what Order’s team actually designed — the real thing, as written:</p><pre>Store<br> ^id:Numeric<br> orders:Order[]<br> address:address.Address<br><br>Order<br> ^id:Numeric<br> milk:Code(MilkType)<br> size:Code(CupSize)<br> type:Code(DrinkType)<br> status:Code(OrderStatus)<br><br>Payment<br> status:Code(PaymentStatus)<br> ^order:Order</pre><p>That ^order:Order line is the whole scenario in one place — Payment doesn&#39;t own Order, it just points at it, and it needs to be right about what&#39;s on the other end of that pointer.</p><h3>What the Payments’ team’s agent actually gets</h3><p>Point Payments’ agent at the same governed jargon.Cafe:0.0.1 release Order&#39;s team publishes, over MCP, and ask it to implement the payment confirmation call.</p><pre>Order.status &gt; Code(OrderStatus)<br>Payment.order &gt; Order (reference)<br><br>Order lifecycle:<br>initial   &gt; Placed     : create new order<br>Placed    &gt; Preparing  : payment<br>Placed    &gt; Cancelled  : cancel order<br>Preparing &gt; Ready      : order is prepared<br>Ready     &gt; Completed  : collect order</pre><p>The agent doesn’t need Order’s team in the room. It doesn’t need last year’s Slack thread. It reads, directly, that payment is only a legal transition from Placed — the same fact Order&#39;s own team is designing against, at the same moment, from the same source. If Order&#39;s team ships a new release tomorrow, Payments&#39; agent reads whichever release it&#39;s pointed at — the current one, or a pinned one it hasn&#39;t upgraded to yet — but it&#39;s never working from a stale picture nobody remembered to update.</p><h3>“Couldn’t they just share a Mermaid diagram?”</h3><p>They could, and this is roughly what most teams actually do — a diagram gets drawn once, dropped in a wiki or a README, and from that point on it’s frozen in whatever state it was in the day someone last remembered to update it.</p><p>That’s the real failure mode, and it’s not about whether Mermaid can express a state machine — it can. It’s that a picture in a wiki has no version, no owner, and no way to notify Payments’ agent that it’s changed. Jargon’s domain releases are addressable and versioned — jargon.Cafe:0.0.1 is a specific, citable thing, and a new release is a new, distinct thing, not a silent edit to the old picture. Payments&#39; agent reads a release, not a rumour of one.</p><p>To be fair to Mermaid: nothing here stops you designing something wrong in Jargon either — it’s not a rules engine, and it won’t reject a lifecycle it disagrees with. The difference was never “Jargon catches your mistakes.” It’s that once designed, it’s one addressable, versioned, machine-readable thing two independent teams can both point at — instead of a picture each side privately, and differently, remembers.</p><h3>“Isn’t this just a schema registry?”</h3><p>Closer, and worth taking seriously — a registry genuinely solves version-compatibility for one schema, one team owns.</p><p>But a registry validates <em>a</em> schema against its own history. It has no way to express that Payment.order refers to an Order that lives in someone else&#39;s domain, with its own lifecycle Payments doesn&#39;t own and shouldn&#39;t be able to edit. That&#39;s a relationship spanning two independently-governed things, not a single evolving artefact — and a registry&#39;s whole design assumes one owner, one schema, one compatibility question. Jargon&#39;s resolved domain carries both Order and Payment, and the reference between them, in the one place either team can read.</p><h3>Read-only, always</h3><p>Payments’ agent can read Order’s lifecycle. It can never write to it. Only Order’s team designs Order — deliberately, together, on their own schedule. Every other consumer, human or agent, just reads. That&#39;s what makes it safe for Payments to trust it without needing a seat at Order&#39;s table.</p><h3>Wrapping up</h3><p>If it’s one repo, one team, one agent — a good spec file in git is probably enough, and I’d say so honestly rather than oversell it. The case for Jargon shows up the moment two things, owned by different people, have to agree on a concept neither of them controls outright: a diagram in a wiki nobody updates, a registry that can’t see across ownership boundaries, or an agent quietly guessing at what the other team’s Order looks like this week.</p><p>There’s also a harder case worth naming: what happens when the concept isn’t yours to govern at all — a regulator’s schema, an RFC, someone else’s vocabulary? That’s a different problem, and a different post.</p><p>If you want to try this on your own domain, <a href="https://jargon.sh/">Jargon’s free to start with</a> — enough to design a domain and see what an agent does with it, before you decide whether it’s worth bringing a second team in properly.</p><p>Questions, or think I’ve got something wrong? Leave a comment, or raise it on the <a href="https://github.com/jargon-sh/issues/issues">issue tracker</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=49dee04eda7c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[JSON Schema Without the Pain]]></title>
            <link>https://jargon-sh.medium.com/json-schema-without-the-pain-044b24d1bbb7?source=rss-88c101c5f802------2</link>
            <guid isPermaLink="false">https://medium.com/p/044b24d1bbb7</guid>
            <category><![CDATA[json-schema]]></category>
            <category><![CDATA[json]]></category>
            <category><![CDATA[api]]></category>
            <dc:creator><![CDATA[Alastair Parker]]></dc:creator>
            <pubDate>Wed, 27 Aug 2025 00:00:21 GMT</pubDate>
            <atom:updated>2025-09-13T11:36:38.167Z</atom:updated>
            <content:encoded><![CDATA[<h4>Generate JSON Schema faster with reusable building blocks</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xW2NEYsGYy0S2lhXTst84g.png" /></figure><p>JSON Schema is one of the most important standards we have for making APIs and data interoperable. It gives teams a common language for validation, tooling, and clarity across projects.</p><p>But writing JSON Schema by hand is often slow and frustrating. Curly braces everywhere. $defs scattered through files. Copy–paste fragments that drift out of sync the moment someone changes a field.</p><p>It’s not that JSON Schema is broken. The challenge is that authoring it manually is hard work.</p><p>That’s why we built <a href="https://jargon.sh/jsonschema">jargon.sh/jsonschema</a>: a free tool powered by Jargon. It lets you describe your model in plain, human-readable text, and instantly see clean JSON Schema on the right.</p><p>The free generator is the simplest view of what Jargon can do, but behind it is a platform for governed, reusable models used by standards bodies and enterprises.</p><h3>Write the model, not the noise</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*0biBhoOvkFaJQdKr" /><figcaption>Generate JSONSchema with our free modelling IDE — based on Jargon</figcaption></figure><p>Instead of starting with braces and boilerplate, you just write the <em>model</em> you want.</p><p>On the left: a simple, human-readable definition.<br>On the right: clean JSON Schema that updates instantly.</p><pre>Order<br>  id:UUID<br>  items:Item[]<br><br>Item:blocks.Product<br>  industryIdentifiers:Unset<br>  description:Unset<br>  productId:blocks.Product.productId<br>  name:blocks.Product.name<br>  sku:blocks.Product.sku<br>  price:Decimal</pre><p>The first class (Order in this case) becomes the schema root. Other referenced classes are pulled into $defs automatically.</p><p>Heres’s the generated schema:</p><pre>{<br>  &quot;$schema&quot;: &quot;https://json-schema.org/draft/2020-12/schema&quot;,<br>  &quot;type&quot;: &quot;object&quot;,<br>  &quot;additionalProperties&quot;: false,<br>  &quot;properties&quot;: {<br>    &quot;id&quot;: {<br>      &quot;type&quot;: &quot;string&quot;,<br>      &quot;format&quot;: &quot;uuid&quot;,<br>      &quot;description&quot;: &quot;&quot;<br>    },<br>    &quot;items&quot;: {<br>      &quot;type&quot;: &quot;array&quot;,<br>      &quot;items&quot;: {<br>        &quot;$ref&quot;: &quot;#/$defs/Item&quot;<br>      },<br>      &quot;description&quot;: &quot;&quot;<br>    }<br>  },<br>  &quot;description&quot;: &quot;&quot;,<br>  &quot;$defs&quot;: {<br>    &quot;Item&quot;: {<br>      &quot;type&quot;: &quot;object&quot;,<br>      &quot;additionalProperties&quot;: false,<br>      &quot;properties&quot;: {<br>        &quot;indusrtyIdentifiers&quot;: {<br>          &quot;type&quot;: &quot;array&quot;,<br>          &quot;items&quot;: {<br>            &quot;$ref&quot;: &quot;#/$defs/Identifier&quot;<br>          },<br>          &quot;description&quot;: &quot;A list of industry identifiers for this Product&quot;<br>        },<br>        &quot;productId&quot;: {<br>          &quot;example&quot;: &quot;ec869053-dce2-4778-982f-5a07f8421206&quot;,<br>          &quot;type&quot;: &quot;string&quot;,<br>          &quot;format&quot;: &quot;uuid&quot;,<br>          &quot;description&quot;: &quot;Unique identifier for the product.&quot;<br>        },<br>        &quot;name&quot;: {<br>          &quot;example&quot;: &quot;Flat White&quot;,<br>          &quot;type&quot;: &quot;string&quot;,<br>          &quot;description&quot;: &quot;Human-readable name for the product.&quot;<br>        },<br>        &quot;sku&quot;: {<br>          &quot;example&quot;: &quot;FW-001&quot;,<br>          &quot;type&quot;: &quot;string&quot;,<br>          &quot;description&quot;: &quot;Stock Keeping Unit.&quot;<br>        },<br>        &quot;price&quot;: {<br>          &quot;type&quot;: &quot;number&quot;,<br>          &quot;format&quot;: &quot;float&quot;,<br>          &quot;description&quot;: &quot;&quot;<br>        }<br>      },<br>      &quot;description&quot;: &quot;A tangible or digital item that can be sold.&quot;<br>    },<br>    &quot;Identifier&quot;: {<br>      &quot;type&quot;: &quot;object&quot;,<br>      &quot;additionalProperties&quot;: false,<br>      &quot;properties&quot;: {<br>        &quot;id&quot;: {<br>          &quot;example&quot;: 9783161484100,<br>          &quot;type&quot;: &quot;string&quot;,<br>          &quot;description&quot;: &quot;The value of this Identifier&quot;<br>        },<br>        &quot;scheme&quot;: {<br>          &quot;example&quot;: &quot;ISBN&quot;,<br>          &quot;type&quot;: &quot;string&quot;,<br>          &quot;description&quot;: &quot;The naming or identifier scheme.&quot;<br>        }<br>      },<br>      &quot;description&quot;: &quot;A general-purpose identifier with a defined scheme.&quot;<br>    }<br>  }<br>}</pre><h3>Reusable building blocks</h3><p>Most teams don’t just struggle with syntax. They struggle with <strong>duplication</strong>. Every project reinvents “Customer,” “Address,” or “Money.”</p><p>That’s why the generator includes the <a href="https://jargon.sh/user/commons/BuildingBlocks/v/latest"><strong>Jargon Commons: Building Blocks</strong></a> domain, a curated library of small, composable classes for common business concepts.</p><p>Some examples:</p><ul><li>Person, ContactDetails, Address for profiles</li><li>Order, LineItem, Money for transactions</li><li>Product, Identifier for catalogues</li></ul><p>Each block is:</p><ul><li><strong>Composable</strong>: extend or trim without breaking the model</li><li><strong>Aligned to DDD</strong>: no inheritance tangles</li><li><strong>Practical</strong>: produces clean JSON Schema ready for APIs and validators</li></ul><h3>What about $ref?</h3><p>JSON Schema already gives you a way to reuse structures with $ref, and that’s a strength of the specification. But working with $ref by hand can be verbose and error-prone, especially when every team reinvents the same components. Jargon takes a different approach: instead of using $ref, it inlines everything into a single schema file. Composition of schemas is treated as a modelling concern, not a JSON Schema concern. The result is a single output that is clean, consistent, and useable in the widest range of tooling.</p><h3>Examples in action</h3><p>Want a Customer with simplified contact details?</p><pre>Customer:blocks.Person  <br>  contact:ContactDetails  <br><br>ContactDetails:blocks.ContactDetails  <br>  email:blocks.ContactDetails.email  <br>  address:Unset  <br>  phone:Unset</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WjWF8wMvNCAOoyq7LBUDKA.png" /></figure><p>Need an Invoice with Products and Money types?</p><pre>Invoice  <br>  invoiceId:UUID  <br>  lineItems:LineItem[]  <br>  total:blocks.Money  <br><br>LineItem  <br>  product:blocks.Product  <br>  quantity:Integer  <br>  unitPrice:blocks.Money</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FzcH6LcM4D0w0oOC_FfxKw.png" /></figure><p>Shipment with customised Address block? Same idea.</p><pre>Shipment  <br>  id:UUID  <br>  destination:Address  <br>  sender:Address  <br><br>Address:blocks.Address  <br>  countryCode:blocks.Address.countryCode</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FX9PsandrYfwad9ESk6WQA.png" /></figure><p>The editor has very comprehensive syntax and validation built in, and checks the correctness of your desings on every keypress:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/880/1*205ZlEYA4wSz3TD9mM2V4w.png" /></figure><h3>Why not just write JSON Schema by hand?</h3><p>You can, and many teams do. But manual schemas are harder to keep consistent, and every new project tends to reinvent the same definitions. That’s why tools and libraries matter: they reduce drift, duplication, and wasted effort.</p><h3>Why this matters</h3><p>JSON Schema gives us a shared standard. But without alignment, every team still ends up with slightly different versions of “Customer,” “Address,” and “Product.”</p><p>That’s how legacy starts: brittle integrations, conflicting reports, and duplicate models that drift apart over time.</p><p>Reusable, governed building blocks change that:</p><ul><li>Teams stay aligned without starting from scratch</li><li>Schemas are faster to create and easier to trust</li><li>Drift and duplication are reduced</li><li>Domain-driven design can be applied cleanly without drowning in curly braces</li></ul><p>Jargon is the platform behind this generator, used by teams in government and the United Nations. The free generator solves syntax pain. The full Jargon platform solves alignment and governance at scale.</p><h3>Not every block will fit</h3><p>The building blocks are designed to cover common concepts, but they won’t fit everyone perfectly. Every organisation has its own quirks. If you find gaps or improvements, you’re welcome to <a href="https://jargon.sh/signup">sign up for a free Jargon account</a> and make suggestions or contribute new blocks.</p><p>And if your team needs more than what’s in the Commons, we’re happy to offer a free trial of Jargon so you can create, extend, and reuse your own models with full governance and versioning built in.</p><h3>Try it yourself</h3><p>Fire up the editor: <a href="https://jargon.sh/jsonschema">jargon.sh/jsonschema</a><br>Explore the <a href="https://jargon.sh/user/commons/BuildingBlocks/v/latest">Building Blocks library</a> (and make <a href="https://jargon-sh.medium.com/introducing-jargon-suggestions-collaborative-domain-and-data-modelling-3fcae6710f56">suggestions</a>!)</p><p>The generator is free, stateless, and ready to experiment with.</p><p>If you’re a developer, start with the free generator.<br>If you’re leading a team or designing standards, explore how Jargon extends this into versioned, governed, reusable domains.</p><p><strong>What’s the most duplicated schema in your organisation?</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=044b24d1bbb7" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Everyone says to shift left.]]></title>
            <link>https://jargon-sh.medium.com/everyone-says-to-shift-left-29021b392e40?source=rss-88c101c5f802------2</link>
            <guid isPermaLink="false">https://medium.com/p/29021b392e40</guid>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[api-design]]></category>
            <category><![CDATA[data-modeling]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[domain-driven-design]]></category>
            <dc:creator><![CDATA[Alastair Parker]]></dc:creator>
            <pubDate>Wed, 30 Apr 2025 11:00:33 GMT</pubDate>
            <atom:updated>2025-09-13T11:35:43.671Z</atom:updated>
            <content:encoded><![CDATA[<p>Nobody shows how. <strong>Here’s how.</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wFiVnaUD3-v8NHJvRN9xsQ.png" /></figure><p>“Shift Left” gets talked about a lot: push quality upstream, catch issues early, make teams more accountable. But when it comes time to actually do it — when you need to model shared meaning, align across domains, and release safely before code even exists — most teams are still stuck in Slack threads and scattered spreadsheets.</p><p>We built <strong>Jargon</strong> to fix that.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PhbUKDobomtdNRJ2EheIfQ.png" /><figcaption><strong>From concept to contract:</strong> Jargon brings business concepts, API design, and lifecycle-aware artifacts into one visual, versioned workspace — so teams can shift left without losing the thread.</figcaption></figure><p>Jargon helps teams:</p><ul><li>Design high-quality, reusable models before writing code</li><li>Apply naming and structure rules as you design, not afterward</li><li>Import and version shared domains, with impact awareness</li><li>Generate OpenAPI and event specs that stay linked to the model</li><li>Keep everything versioned, traceable, and visible to everyone</li></ul><p>We’ve put together a <strong>real walkthrough</strong>, using a fictional retail example, to show what it looks like to shift left in practice. It’s not a whiteboard sketch. It’s real models, evolving in a real tool, with screenshots at every step.</p><p><a href="https://jargon.sh/shift-left"><strong>Explore it here → jargon.sh/shift-left</strong></a></p><h3>What’s in the walkthrough?</h3><p>We use the classic banana protector example (thanks Mauro Servienti) to walk through the entire flow of modelling, versioning, and governing a domain from scratch.</p><p>Each of the 11 steps is backed by screenshots and actual model behaviour inside Jargon.</p><pre><br>           Step                                  What you&#39;ll learn                      <br> -------------------------- ----------------------------------------------------------- <br>  1. Conceptual modeling     Map out the key business resources and how they relate     <br>  2. Domain boundaries       Group those concepts into teams and responsibilities       <br>  3. Design rules            Apply structure and naming rules live in the editor        <br>  4. Suggestions             Make safe, collaborative proposals with semantic diffs     <br>  5. Versioning              Release changes with confidence and clarity                <br>  6. Imports                 See when upstream domains change-and what&#39;s safe to adopt  <br>  7. Lifecycles              Model valid state transitions directly in the design       <br>  8. Ripple tracing          Trace how changes impact downstream teams or domains       <br>  9. Town plan rollout       Replace placeholders with live domains over time           <br>  10. API generation         Get OpenAPI and event specs directly from the model        <br>  11. Traceable artifacts    Keep everything tied to the domain it came from </pre><p><a href="https://jargon.sh/shift-left"><strong>Read the full walkthrough → jargon.sh/shift-left</strong></a></p><h3>Want a deeper dive?</h3><p>If you want to go beyond the high-level view, we also created a three-part series walking through every decision in detail. Same banana protector example, more hands-on.</p><ul><li><strong>Part 1: Conceptual modelling</strong><br> Break down the problem space and sketch out the resources.<br> <a href="https://medium.com/@jargon-sh/a-worked-example-of-using-jargon-for-domain-driven-design-part-1-e8e85452d192">Read it →</a></li><li><strong>Part 2: Town Planning</strong><br> Map out your domains, group them, and design for maturity.<br> <a href="https://medium.com/@jargon-sh/a-worked-example-of-using-jargon-for-domain-driven-design-part-2-2493c14d204">Read it →</a></li><li><strong>Part 3: Domain modelling</strong><br> Implement two domains, wire up identifiers and state, and track rollout.<br><a href="https://medium.com/@jargon-sh/a-worked-example-of-using-jargon-for-domain-driven-design-part-3-60e06c11f8bd">Read it →</a></li></ul><h3>Why it matters</h3><p>If you care about Shift Left, this walkthrough gives you something solid to point at. It’s not another diagram. It’s an example you can reuse, adapt, or challenge.</p><p>We’re not here to pitch another opinion about the future of data. We’re showing what it looks like when you act on the principles — and where the friction starts to disappear.</p><p><a href="https://jargon.sh/shift-left"><strong>Walk through it here</strong></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=29021b392e40" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[10 Teams. 10 Models. 0 Alignment.]]></title>
            <link>https://jargon-sh.medium.com/10-teams-10-models-0-alignment-399503a4e38b?source=rss-88c101c5f802------2</link>
            <guid isPermaLink="false">https://medium.com/p/399503a4e38b</guid>
            <category><![CDATA[ddd]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[integration]]></category>
            <category><![CDATA[data-modeling]]></category>
            <dc:creator><![CDATA[Alastair Parker]]></dc:creator>
            <pubDate>Sat, 12 Apr 2025 21:24:34 GMT</pubDate>
            <atom:updated>2025-09-13T11:34:56.913Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xspuKGvQN2qfQf8l6LB2hA.png" /></figure><p>You’ve seen this before. Each team swears they’re building from the same model. The names are familiar. The concepts overlap. But nothing lines up.</p><ul><li>The API team has Client.</li><li>The data warehouse calls it Customer.</li><li>The product team prefers User.</li><li>And the legal team insists on Individual.</li></ul><p>They’re all correct — in their own context. But without alignment, those differences lead to drift and distrust.</p><h3>The Quiet Cost of Fragmentation</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*E8rAwvgOsWX5DpXVzUBfIw.png" /></figure><p>At first, it seems harmless. You let each team model things “the way that works for them.” But then:</p><ul><li>APIs become inconsistent</li><li>Data pipelines break across services</li><li>Downstream consumers can’t trust the definitions</li><li>The model needs to change, and no one knows what to update</li></ul><p>What starts as flexibility becomes friction.</p><h3>Why It Happens</h3><p>Because modelling happens in isolation — and without a shared language across teams:</p><ul><li>Teams create artifacts — OpenAPI, JSON Schema, Excel templates — without shared ownership.</li><li>Naming is local, versioning is siloed, and diagrams are out of date.</li><li>Nobody sees the overlap until it’s already shipped.</li></ul><p>And once it’s live, it’s “too late to fix.”</p><h3>What Jargon Does Differently</h3><p>Jargon supports distributed modelling — but with shared visibility, structure, and feedback:</p><ul><li><strong>Shared domains</strong> with real-time visibility into reuse, changes, and conflicts</li><li><strong>Suggestions</strong> that let teams propose updates without overwriting each other</li><li><strong>Semantic diff and auto-versioning</strong> to understand exactly what’s changing</li><li><strong>Generated artifacts</strong> that stay in sync: JSON Schema, OpenAPI, Readmes, JSON-LD</li></ul><p>And because everything’s structured declaratively, Jargon helps:</p><ul><li>Spot duplication early</li><li>Align naming and ownership</li><li>Prevent drift before it becomes tech debt</li></ul><h3>What To Do Next</h3><ul><li>Accept that multiple models are normal — but unaligned models are risky</li><li>Model together, not in silos</li><li>Use tools that treat data models like living, evolving systems</li></ul><p>10 teams don’t need one model — but they do need alignment. That means shared intent, visible dependencies, and clarity around how similar concepts relate across contexts.</p><p>Want to see how this works in practice? <a href="https://jargon.sh/">Start here.</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=399503a4e38b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Linked Data, Unlinked Teams]]></title>
            <link>https://jargon-sh.medium.com/linked-data-unlinked-teams-a065aab526d7?source=rss-88c101c5f802------2</link>
            <guid isPermaLink="false">https://medium.com/p/a065aab526d7</guid>
            <category><![CDATA[linked-data]]></category>
            <category><![CDATA[ontology]]></category>
            <category><![CDATA[data-modelling]]></category>
            <dc:creator><![CDATA[Alastair Parker]]></dc:creator>
            <pubDate>Sat, 12 Apr 2025 21:07:58 GMT</pubDate>
            <atom:updated>2025-09-13T11:34:20.104Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Yvv8xa9y1_rpQ_n5DKCxdA.png" /></figure><p>You followed the standards. You mapped to schema.org. You used JSON-LD. Your RDF passes validation.</p><p>And yet — your API is drifting, your model is misunderstood, and your teams are each using the same terms in slightly different ways.</p><p>Welcome to the <em>illusion</em> of alignment.</p><p>Linked Data is supposed to create clarity. But too often, it only connects the <em>data</em> — not the <em>people</em>. What you get is a technically correct model that fails in implementation.</p><h3>The Semantic Trap</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Z2wThKrSzJbTd5JcQuvd0g.png" /></figure><p>Semantic web technologies are powerful. They let us formally describe how data relates to the world. But there’s a hidden assumption baked into RDF, JSON-LD, and OWL:</p><blockquote><em>That all stakeholders interpret the model the same way.</em></blockquote><p>In reality:</p><ul><li>The product team reuses Product with its own tweaks.</li><li>The regulator expects Asset to mean something legally binding.</li><li>The dev team ships an API where @id isn’t stable.</li></ul><p>Each of these teams is “linked” — but not aligned. And without alignment, Linked Data becomes Linked Doubt.</p><h3>Why This Happens</h3><p>Most semantic systems treat modelling as a vocabulary exercise:</p><ul><li>Choose terms.</li><li>Define relationships.</li><li>Add a context.</li></ul><p>But that doesn’t define:</p><ul><li>What’s required</li><li>Who owns what</li><li>What the data <em>means</em> in each lifecycle state</li><li>How different systems should interpret or validate it</li></ul><h3>What Jargon Does Differently</h3><p>Jargon assumes your ontology is the starting point — not the finish line.</p><p>It provides:</p><ul><li><strong>Declarative modelling</strong> with structure, constraints, and lifecycle</li><li><strong>Design rule validation feedback</strong> during modelling</li><li><strong>Team collaboration</strong> through Suggestions and semantic diff</li><li><strong>Generated artefacts</strong> like OpenAPI, JSON Schema, Readmes, and even JSON-LD</li></ul><p>So when someone redefines Product, you see the impact immediately. When a team proposes a change, you can track and validate it across the entire domain. And when you release a model, everyone is literally on the same page.</p><h3>What To Do Next</h3><p>If your linked data feels more like a group project with no shared brief:</p><ul><li>Reframe the goal: You’re not just linking data, you’re aligning teams.</li><li>Stop treating vocab as your model.</li><li>Build structure, lifecycle, and intent into the heart of your design.</li></ul><p>And maybe don’t rely on &lt;skos:means&gt; to align your people.</p><p>Want to see how Jargon makes this practical? <a href="https://jargon.sh/">Start here.</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a065aab526d7" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SpecDevOps: The Missing Loop Before Dev and Ops]]></title>
            <link>https://jargon-sh.medium.com/specdevops-the-missing-loop-before-dev-and-ops-20a3f086eb92?source=rss-88c101c5f802------2</link>
            <guid isPermaLink="false">https://medium.com/p/20a3f086eb92</guid>
            <category><![CDATA[api-design]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[digital-transformation]]></category>
            <category><![CDATA[software-architecture]]></category>
            <dc:creator><![CDATA[Alastair Parker]]></dc:creator>
            <pubDate>Thu, 10 Apr 2025 02:52:33 GMT</pubDate>
            <atom:updated>2025-09-13T11:33:31.599Z</atom:updated>
            <content:encoded><![CDATA[<h4>DevOps helped us ship faster. Now it’s time to build systems that last.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*e2Tu1D9VjEkGcAGPdVETBg.png" /></figure><p><strong>The Legacy Paradox</strong></p><p>DevOps has reshaped how we build and deploy software. Shipping fast, integrating often, and monitoring continuously has become standard practice. Yet despite all this, we keep ending up with legacy.</p><p>Not legacy infrastructure, but legacy intent.</p><p>APIs that work, but no one knows what they were for. Data models that validate, but no longer match how the business operates. Documentation that drifts, assumptions that rot, and institutional knowledge that fades.</p><p>DevOps helped us build it right. But what if we never built the right thing to begin with?</p><p><strong>The DevOps Loop Starts Too Late</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ftFLJVNJ3q24uxQmqKaTmg.png" /></figure><p>The DevOps loop is powerful. It gave us automated testing, rapid feedback, and infrastructure as code.</p><p>But it assumes that the specifications, models, and semantics that define <em>what</em> we’re building are already correct. That they’re versioned. Governed. Reliable.</p><p>That’s rarely true.</p><p>Most specs live in wikis, spreadsheets, static docs, or someone’s head. They aren’t treated like the first-class artifacts they are. So as teams scale and systems evolve, those specs drift from reality.</p><p>And just like that, we’re building legacy again.</p><p><strong>SpecDevOps: A New Discipline for Durable Systems</strong></p><p>SpecDevOps is a natural evolution of DevOps thinking — one level earlier in the stack.</p><p>It brings the same agility, automation, and governance we apply to code and infrastructure… to the specs themselves.</p><p>This isn’t about product design, user stories, or agile task management. SpecDevOps complements those efforts — but its focus is technical: ensuring that data models, API specifications, and machine-readable contracts are accurate, aligned, and interoperable.</p><p>With SpecDevOps:</p><ul><li>Your domain models live in versioned, collaborative environments</li><li>Changes are proposed, reviewed, and released with traceable intent</li><li>Artifacts like JSON Schema, JSON-LD, and OpenAPI are generated automatically</li><li>Teams get feedback loops before they write a single line of code</li></ul><p>SpecDevOps doesn’t replace DevOps. It completes it.</p><p><strong>Jargon: The Platform for SpecDevOps</strong></p><p>Jargon is built from the ground up for SpecDevOps.</p><p>It gives you:</p><ul><li><strong>Structured modeling</strong> with real-time validation and reuse across teams</li><li><strong>Governance</strong> that supports suggestions, diffs, semantic versioning, and change reviews</li><li><strong>Artifact automation</strong> so your models always produce up-to-date schemas, API docs, and linked data</li><li><strong>Release hooks</strong> that push updates into GitHub, data portals, and pipelines</li></ul><p>Jargon is how teams align meaning <em>before</em> they align implementations.</p><p><strong>Build What You Mean. Build It So It Lasts.</strong></p><p>DevOps taught us to ship fast and fix forward.</p><p>SpecDevOps reminds us to start from clarity. To treat the specs, models, and semantics of our systems with the same care we treat the code.</p><p>Because 20 years from now, someone will inherit what you built.</p><p>If they can see what it was meant to do, you’ve left a legacy that lasts.</p><p>If not, you’ve left another mess.</p><p><strong>SpecDevOps is here. <br>And it starts with Jargon.</strong><br><a href="https://jargon.sh/">https://jargon.sh</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=20a3f086eb92" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How the UN/CEFACT Transparency Protocol Team Built and Deployed Digital Product Passport…]]></title>
            <link>https://jargon-sh.medium.com/how-the-un-cefact-transparency-protocol-team-built-and-deployed-digital-product-passport-3fa7492b9a7e?source=rss-88c101c5f802------2</link>
            <guid isPermaLink="false">https://medium.com/p/3fa7492b9a7e</guid>
            <category><![CDATA[data-governance]]></category>
            <category><![CDATA[linked-data]]></category>
            <category><![CDATA[data-modeling]]></category>
            <category><![CDATA[api]]></category>
            <category><![CDATA[digital-product-passport]]></category>
            <dc:creator><![CDATA[Alastair Parker]]></dc:creator>
            <pubDate>Tue, 08 Apr 2025 10:32:05 GMT</pubDate>
            <atom:updated>2025-09-13T11:32:40.191Z</atom:updated>
            <content:encoded><![CDATA[<h3>How the UN/CEFACT Transparency Protocol Team Built and Deployed Digital Product Passport Vocabularies — With Automation, Governance, and Interoperability at Scale</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8Cq7ilnlCKt02LxohabKcQ.png" /></figure><p><em>…and automatically generated JSON-LD, JSON Schema, and documentation from a suite of loosely coupled but cohesive models — following domain-driven design principles to avoid monolithic complexity while preserving semantic alignment.</em></p><p><strong>1. The challenge</strong></p><p>The UN/CEFACT Transparency Protocol (UNTP) team set out to improve visibility and trust in global trade by enabling the seamless sharing of product information. Achieving this at scale requires not just technical infrastructure, but well-defined, machine-readable semantics that can be reliably implemented and understood at every step in a product’s journey — from creation to final destination. To support this, they needed structured vocabularies for the Digital Product Passport (DPP) that could:</p><ul><li>Align with linked data principles via JSON-LD — not just as a semantic add-on, but as a foundational mechanism for connecting distributed claims and technical documents throughout a product’s lifecycle. Each document is linked to shared identifiers and expanded into a knowledge graph, enabling regulators and supply-chain actors to see the full picture.</li><li>Produce valid, usable JSON Schemas that simplify the job of implementers by generating code and validation rules, making semantic and syntactic interoperability achievable across diverse systems</li><li>Be clear, version-controlled, and auditable — especially as global trade relationships evolve, requiring specifications to adapt quickly and reliably to shifting regulatory, commercial, and geopolitical contexts</li><li>Enable end-to-end automation in publishing, management, and governance — eliminating manual effort and human error, and ensuring specifications can evolve with confidence and clarity at scale</li></ul><p>Like many standards efforts, the team began with narrative documents and spreadsheets. But as the scope grew, so did the complexity: version control became difficult. JSON-LD, in particular, proved far more esoteric than JSON Schema, with a steeper learning curve and fewer mainstream tooling options.</p><p><strong>2. The solution</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*88kSmKK3DwyZz0Dype2yMA.png" /><figcaption>Here’s a snapshot of the actual DPP domain inside Jargon — with definitions, relationships, and outputs all driven from the same model.</figcaption></figure><p>Jargon was introduced to bring structure, reusability, and automation to the process. The UNTP team retained full control of their models and vocabulary design, while Jargon served as the platform to express those designs clearly and operationalise them across teams.</p><p>With close collaboration from the UNTP team, Jargon found a way to thread the needle — generating JSON-LD and JSON Schema artefacts that interoperated seamlessly from a single domain model.</p><p>Jargon made it possible to:</p><ul><li>Define core classes and relationships using a readable domain language</li><li>Annotate RDF triples directly within the model to convey specific semantic intent</li><li>Reuse models across multiple domains, improving consistency and reducing duplication</li><li>Enable Git-style collaboration — with suggestions, diffs, versioning, and approvals</li><li>Auto-generate JSON-LD context + graph files, JSON Schema, and OpenAPI specs from the same model</li><li>Trigger webhook events upon release to integrate with deployment pipelines</li></ul><p>Because all outputs were generated automatically from the model, the team could rapidly test, revise, and iterate. Feedback from early implementers led directly to changes in the models — and those changes flowed instantly through to downstream tools and documents. What would have taken days or weeks in a manual process became a matter of minutes.</p><p><strong>3. Release integration with GitHub</strong></p><p>To make the vocabulary lifecycle seamless from authoring to publication, the UNTP team configured Jargon to emit webhooks upon release.</p><p>These webhooks:</p><ul><li>Trigger GitHub Actions to rebuild and publish the official specification site</li><li>Push the latest JSON-LD and JSON Schema to a public GitHub repo</li><li>Ensure all tooling and documentation stays synchronised with the latest version</li></ul><p>This eliminated fragile, manual steps — and ensured consistency between internal models, public schemas, and live documentation.</p><p><strong>4. The outcome</strong></p><p>The UNTP team now publishes:</p><ul><li>Clean, modular domain models covering traceability, conformity, circularity, and more</li><li>JSON-LD vocabularies and context files aligned to semantic web standards</li><li>JSON Schemas and OpenAPI definitions to drive real-world implementation</li><li>Developer-facing documentation and diagrams to aid adoption</li></ul><p>All of these artefacts come from a single, governed source of truth — reducing drift, improving transparency, and enabling traceable collaboration.</p><p>Explore the live models:<br>🔗 <a href="https://jargon.sh/user/unece">https://jargon.sh/user/unece</a></p><p>View the official spec site:<br>🔗 <a href="https://uncefact.github.io/spec-untp/">https://uncefact.github.io/spec-untp/</a></p><p><strong>5. Why this matters</strong></p><p>This isn’t just about ontology or schema generation. It’s about enabling agile standards development — where real-world implementation, semantic integrity, and machine-readability go hand-in-hand.</p><p>The result? A future-proof foundation for DPP adoption that evolves as fast as the global trade environment demands.</p><p><strong>6. Want to try it?</strong></p><p>If you’re building a vocabulary, data exchange format, or API spec — especially in sustainability, supply chains, or government — Jargon might be worth a look.</p><p>You can use it free to create, reuse, and release domains. Publishing JSON-LD, schemas, and docs is available as part of the paid tier.</p><p>We’re happy to offer a one-month trial or help walk through a real use case.</p><p>🔗 <a href="https://jargon.sh/">https://jargon.sh</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3fa7492b9a7e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Modernising Enterprise Architecture: Bridging Legacy Systems with Jargon]]></title>
            <link>https://jargon-sh.medium.com/modernising-enterprise-architecture-bridging-legacy-systems-with-jargon-630f2e800e26?source=rss-88c101c5f802------2</link>
            <guid isPermaLink="false">https://medium.com/p/630f2e800e26</guid>
            <category><![CDATA[enterprise-technology]]></category>
            <category><![CDATA[enterprise-architecture]]></category>
            <category><![CDATA[data]]></category>
            <category><![CDATA[legacy]]></category>
            <dc:creator><![CDATA[Alastair Parker]]></dc:creator>
            <pubDate>Thu, 13 Mar 2025 04:51:23 GMT</pubDate>
            <atom:updated>2025-09-13T11:31:56.401Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fcHL32G3XCdaDXIz30w0Fw.png" /></figure><p>Enterprise architecture tools have a reputation. They are powerful, widely used, and deeply embedded in large organisations — but they are often opaque, slow-moving, and painful to maintain. Migrating away from them entirely is rarely an option, no matter how much better alternatives might be.</p><p>But what if the key to modernisation isn’t replacing these tools, but making them easier to work with, more collaborative, and better integrated into modern workflows? Meet <a href="https://jargon.sh/">Jargon</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cNF1fVasucZu-SoxQL-OXw.png" /></figure><h3>Enterprise Architecture vs. Modern Development Approaches</h3><p>Large organisations — especially in finance, government, and heavily regulated industries — rely on enterprise architecture (EA) platforms to govern data, standardise system design, and ensure compliance. These platforms promise centralised control and enterprise-wide visibility.</p><p>However, in practice, teams often face major issues:</p><ul><li><strong>Top-down bottlenecks</strong> — EA tools are controlled by a central group, making it difficult for delivery teams to contribute effectively.</li><li><strong>Bottom-up silos </strong>— Individual teams create their own models and specifications outside the EA system, leading to inconsistency.</li><li><strong>Limited access and usability </strong>— The tools themselves are often complex, locked down, or difficult to integrate into modern workflows.</li></ul><p>The result? A growing gap between the enterprise-wide architecture and the actual work being done on the ground — creating long-term technical debt that makes future innovation harder.</p><h3>Jargon as the Integration Layer</h3><p>Rather than trying to replace these platforms, Jargon can bridge the gap, making enterprise architecture more accessible, versioned, and developer-friendly.</p><p>Take a look at any modern integrated system, and you’ll see technologies built around OpenAPI, JSON Schema, and increasingly JSON-LD — ecosystems that enable automation, interoperability, and real-time collaboration. However, enterprise architecture tools often remain tied to XML-based workflows like XMI or CSV — formats that were designed for a different era. These workflows struggle to adapt to modern APIs, making integration with cloud-native and DevOps tooling cumbersome. This results in slow iteration cycles, increased manual effort, and reduced collaboration between teams. The growing gap between enterprise-wide architecture and the actual work being done on the ground leads to manual processes, poor integration, and limits how effectively teams can work across modern DevOps environments — ultimately creating the next generation of rigid, hard-to-maintain systems — repeating the mistakes of the past.</p><p>Jargon eliminates these issues by:</p><ul><li><strong>Providing a structured pipeline</strong> for enriching enterprise models. Jargon imports content in formats that enterprise platforms support (such as XMI), adds structured metadata and validation, and then exports it back again.</li><li><strong>Acting as a collaboration layer </strong>that enables developers to work with models without direct access to the EA tool.</li><li><strong>Bringing version control, automation</strong>, and review workflows to a traditionally manual, document-heavy process.</li></ul><p>Instead of treating enterprise architecture as a walled-off function, Jargon enables continuous integration between high-level architecture and real-world software design — bridging the gap between enterprise-wide planning and hands-on development while automating validation and collaboration.</p><h3>A Roadmap for Enterprise Integration</h3><p>Jargon is already working with organisations to bridge the gap between modern API-first design and legacy enterprise tooling, enabling teams to modernise workflows without abandoning existing systems. While our support for OpenAPI and JSON Schema is already in place, we’re planning to add XMI support to bring Jargon’s benefits to a wider audience of enterprises who use legacy architecture tools. By supporting XMI, Jargon will allow enterprises to unlock their existing architecture investments while seamlessly integrating API-driven workflows. This helps address the challenge of top-down governance conflicting with bottom-up development needs, enabling smoother collaboration across teams. This roadmap is actively evolving, and we see an opportunity to expand further by working with organisations navigating these challenges:</p><ul><li>Expanding Jargon’s capabilities to support seamless data integration across enterprise systems, ensuring structured data remains portable and interoperable.</li><li>Expanding visualisation and collaboration options, incorporating formats like Mermaid and PlantUML to enhance architectural clarity.</li><li>Creating automation pipelines for enterprise platforms, ensuring seamless import, enrichment, and re-export into the existing EA toolchain.</li></ul><p>We’re keen to work with forward-thinking organisations that want to bring modern DevOps practices into enterprise modelling — whether that’s through API governance, automation, or breaking down bottlenecks in architecture workflows.</p><p>If you’re navigating these challenges, <a href="https://jargon.sh/">let’s talk</a>. We’d love to explore how Jargon can fit into your roadmap — whether you’re modernising how your organisation manages data or building modern API-enabled systems. <a href="https://jargon.sh/pledge">Schedule a call with us to explore how.</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=630f2e800e26" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Introducing Jargon “Suggestions”: Collaborative Domain and Data Modelling]]></title>
            <link>https://jargon-sh.medium.com/introducing-jargon-suggestions-collaborative-domain-and-data-modelling-3fcae6710f56?source=rss-88c101c5f802------2</link>
            <guid isPermaLink="false">https://medium.com/p/3fcae6710f56</guid>
            <category><![CDATA[domain-driven-design]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[api]]></category>
            <dc:creator><![CDATA[Alastair Parker]]></dc:creator>
            <pubDate>Mon, 20 Jan 2025 21:56:00 GMT</pubDate>
            <atom:updated>2025-09-13T11:31:10.056Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*872PiQSnbkGVz42caCiJIw.png" /></figure><p>We’re thrilled to announce the release of Suggestions, a powerful new feature in Jargon that revolutionises how teams collaborate on domain and data modelling. This addition combines the best practices of open-source collaboration with the unique challenges of designing complex data models, giving teams the tools they need to streamline workflows, improve quality, and save time.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*E-IL205rQYM0GFXpoxmyNA.png" /><figcaption>Jargon is an innovative platform for helping organisations modernise their systems with collaborative Domain and API design.</figcaption></figure><h4>Solving the Collaboration Challenge</h4><p>Domain and data modelling is traditionally a manual, siloed processes, making collaboration across teams difficult and prone to miscommunication. With Suggestions, we’ve tackled this challenge head-on. Now, team members can propose new changes to a domain, share them for feedback, and collaborate in a non-destructive and open way. This feature enables users to “show, don’t tell” their ideas, fostering shared ownership of domains while maintaining clarity and control.</p><h4>Why Suggestions Stands Out</h4><p>Suggestions brings tried-and-true collaboration mechanisms from the open-source software community into the world of data modelling. Here’s how it makes a difference:</p><ul><li><strong>Clarity in Change Management</strong>: See exactly what changes are being proposed.</li><li><strong>Impact Visualisation</strong>: Understand how suggested changes affect the domain.</li><li><strong>Conflict Resolution</strong>: Be alerted to potential conflicts and address them early.</li></ul><p>This approach saves teams significant time and effort while improving the quality and consistency of their domains. By streamlining collaboration, Jargon ensures that teams can focus on building better models rather than getting bogged down in manual processes.</p><h4>How It Works</h4><p>Using Suggestions is simple and familiar to anyone using modern DevOps tooling.</p><h4>Creating a suggestion</h4><ol><li>Open a Domain and make some modifications.</li><li>Instead of saving changes to a domain, users can create a suggestion.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/832/1*BtP7eCZ4M0GB_UVN6u5VpQ.png" /><figcaption>Jargon’s new Suggestion Buttons. Create or expand a suggestion (the light-bulb), or merge and accept.</figcaption></figure><h4>Browsing and finding suggestions</h4><p>On the Domain’s detail page, there’s a new tab for suggestions that allows you to browse, search and filter for suggestions. Each suggestion shows you the number of comments, and the number of updates made.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hZj8EcqFykJ7tseyil4FQg.png" /><figcaption>Browse, search and filter suggestions</figcaption></figure><h3>Examining a Suggestion</h3><p>Opening a suggestion takes you to the details page, where you can see the updates, conversations and specific changes made.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*waatxOozf1vYEPH832kRlQ.png" /><figcaption>Jargon identifies and breaks down the different types of changes made in a suggestion</figcaption></figure><p>You can also visualise the state of the Domain for any updates made, or view the combined suggestion before accepting and merging:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yb9Is2bo2BwHTfESq9hb9g.png" /></figure><h3>Accepting and merging a Suggestion</h3><p>Once you’re ready to accept a Suggestion, Jargon will automatically merge the changes it can, and will guide you through the conflicts that you need to resolve, give you options to choose from, and ultimately confirm before merging.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kCgqKxTQegMygmwL9Vb4Ng.png" /><figcaption>Jargon has detected a conflict in the Domain model that you will need to resolve</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YA9ha14Q60Mzs54XN68r8g.png" /><figcaption>For each conflict, Jargon will present you with the option to keep the initial or suggested changes.</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zoacYxcKLF9YVsTnkcN_Jg.png" /><figcaption>When there are no more conflicts, Jargon will let you merge and close the Suggestion.</figcaption></figure><h4>Available for Teams</h4><p>Suggestions is available to all users within teams, making it an essential tool for organisations looking to bring structure and agility to their data modelling efforts.</p><h4>Explore More</h4><p>The release of Suggestions marks a significant milestone in our journey to transform the way enterprises approach data modelling and API design. It’s not just a feature — it’s a step forward in making Jargon the go-to platform for innovative and collaborative design.</p><p>Curious to see what other innovative features Jargon has to offer? Dive in and discover how our platform is helping teams around the world build better domains, faster.</p><p>Sign up today for a free account, or reach out to learn more or book a trial!</p><p><a href="https://jargon.sh/">https://jargon.sh</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3fcae6710f56" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>