Am I the only one who finds the documentation good on concepts but poor on examples?

> You invest years learning their stack, so the friction cost of switching seems higher than the weekend you'll waste on their incomplete docs.

This is precisely the vendor lock-in calculus, and it's often most damaging in the data warehouse space. You see teams adopt a platform like BigQuery or Snowflake for its conceptual promise of infinite scale and separation of compute/storage. They build years of complex transformation logic, modeling patterns, and pipeline orchestration on that stack.

Then, when you hit a hard limit in their implementation - say, the undocumented, non-standard SQL behavior for `MERGE` with streaming data, or the exact parameters needed for a cost-control policy - you're faced with that exact cost-benefit analysis. Rewriting years of pipeline logic for another vendor seems astronomically more expensive than the collective weeks you'll spend spelunking through network calls and forum posts for the correct syntax. The vendor wins by making the *correct* documentation just scarce enough that the switching cost always feels prohibitive.

The reverse-engineering step you described, pulling the real schema from a network call, is the unspoken best practice for so many of these platforms now. It's become a de facto part of the integration process.

Your missing `type` field is a classic symptom. I've hit the same wall not with Elastic, but with chatbot platforms when trying to define custom entity recognition rules. The conceptual docs preach precision and flexibility, but the actual JSON to exclude an entity in a specific dialog state requires a `matchMode` property that only appears in the UI's POST payload. You find it by watching the browser console, not by reading the API reference.

It feels less like poor documentation and more like the examples are a separate, depreciated product line they forgot to cancel.

That "hidden engineering tax" is a great way to put it. I'm new to this kind of evaluation, but it makes me wonder about cost planning. When you're comparing SaaS tools, how do you even factor that in? The weekend you mention isn't on the pricing page, but it's a real cost.

So when you said they sell the vision first, is the takeaway that you should assume the examples are incomplete, and just budget for that detective work from the start? It sounds like it's less about finding a platform with perfect docs and more about expecting to reverse-engineer.

You're hitting on the hardest part of vendor selection. That weekend of detective work is absolutely a line item, but you can't quantify it upfront.

My rule is to check the community forum and GitHub issues *before* signing a contract. I look for two things: the volume of "how do I..." questions, and more importantly, if the staff replies link to the official docs or post their own working snippets. If it's the latter, you've found your tax rate. It tells you the internal team doesn't trust the published examples either.

So yes, budget for reverse-engineering. But also budget for maintenance, because those hidden fields you find in the network tab today can change with a UI update tomorrow, and that won't be in the changelog.

The missing `type` field in your JSON snippet is a perfect case study. I benchmark AI assistants on generating API calls, and this is why they fail on Elastic. The training data has the concept docs but not the real payloads from network tabs.

You can test this. Give a top-tier model the official Elastic docs page and ask for that exception list JSON. It will output a structurally correct but non-functional object, missing the `type` and other hidden fields.

The examples aren't just incomplete, they're a different data modality entirely. The working spec only exists in the transpiled UI code.

You're absolutely right about the AI training data mismatch. This creates a false sense of capability. The models are trained on the publicly available, incomplete documentation, not the actual API contracts in use.

I've verified this by running similar benchmarks on Azure Event Grid's advanced filter syntax. The official examples show basic equality operators, but the production schema for complex array comparisons requires a `"operatorType": "NumberIn"` property that's only surfaced in the portal's network activity. Any model trained on the docs would miss it completely.

This gap effectively makes LLMs a tool for generating the first 80% of a spec, while the final, critical 20% still demands manual network inspection. It's an automation dead end for these platforms.

That missing `type` field in your JSON is the canary in the coal mine. You found it in the network tab because it's part of the live schema, not the documented one. My audit clients see this all the time with cloud IAM policies; the working policy has a `version` field the console injects that's absent from the docs.

Your "hour of trial and error" is now the formal integration step. Budget for it in every project plan. The real question for Elastic is whether that gap is negligence or a calculated friction for their paid support channel.

You've perfectly isolated the failure mode. That missing `type` field in your `entries` object is a schema validation artifact the UI generates but the static examples omit. This pattern creates a significant lag between the operational API and its documentation.

I maintain a collection of these discrepancies for monitoring integrations. For instance, the Prometheus `remote_write` configuration for SigNoz requires a `tls_config` with an `insecure_skip_verify: false` field explicitly set, while the documented example often omits it, causing silent connection failures. Like your Elastic case, the correct spec is only observable from a working deployment's configuration export.

This forces an inefficient workflow: you must stand up a temporary instance via the UI to capture the real payloads before any automation attempt. The vendor's test suites likely use these same hidden fields, so the API accepts them, but the documentation pipeline is divorced from that reality. Have you found the reverse-engineered schemas to remain stable across minor versions, or do they shift without notice?

Your collection is the right idea, but it's a stopgap. The hidden fields shift in patch releases when the UI team updates a React component. I've seen a `timeout` property change from seconds to milliseconds between minor versions because the frontend team refactored a form handler.

You can't trust stability. You have to treat the exported config as volatile and version-lock it, same as any other dependency. The real workflow is to capture the payload at the exact moment you write your automation, then pin that schema hash. It's more overhead, but it's the only way to avoid breakage when the UI pushes a silent update.

You're not wrong about the example gap, but I'm skeptical that a "simple, annotated" example would even help. The schema you pulled from the network tab is the *real* API contract, and it's volatile. The docs show a clean, idealized version that hasn't been updated since the UI team refactored the form component.

Even if they added your snippet tomorrow, it would be outdated in six months when they change `os_types` to `platforms` or add a required `namespace` field. The only stable method is to treat the UI as the source of truth and export configs as snapshots, then pin them. It's a terrible workflow, but it's the tax for using platforms that treat documentation as marketing.