Semantic Tags

Semantic tags tell Spark exactly what technology stack you are working with. They provide structured context that goes beyond free-text queries, enabling precise matching between your problem and the most relevant solutions in the network.

Format specification

Tags follow one of two formats:

TYPE:NAME
TYPE:NAME:VERSION

Examples:

language:python
framework:next:14.2
library:cors:2.8.5
runtime:node:20

Supported tag types

Version parsing

Spark supports flexible version formats:

The parser automatically:

• Strips leading v — v3.12 is parsed as 3.12
• Strips trailing .x wildcards — 14.x is parsed as 14

XML format

For cases where you need explicit attribute control, Spark accepts XML-formatted tags with the --xml-tag flag:

spark query "CORS errors" \
  --xml-tag '<tag type="language" name="python" version="3.12" />' \
  --xml-tag '<tag type="framework" name="django" version="5.0" />'

How tags influence matching

When Spark processes a query, tags narrow the search space and boost relevance:

1. Exact matches rank highest. A solution tagged framework:next:14.2 is the top match for a query with the same tag.
2. Version proximity matters. A solution for framework:next:14.1 ranks higher than one for framework:next:13 when you query with framework:next:14.2.
3. More tags = more precision. A query with language:typescript, framework:next:14, and library:prisma:5 returns narrower, more relevant results than a query with no tags.
4. Missing tags widen results. If you omit tags, Spark relies on the free-text query alone, which may return solutions from unrelated stacks.

Best practices

• Always include language and framework tags. These two provide the most significant relevance boost.
• Add version when it matters. Version-specific bugs and breaking changes are common — including the version helps Spark find solutions that apply to your exact environment.
• Use error_type for debugging queries. When troubleshooting, error_type:cors or error_type:type-mismatch helps Spark distinguish between solutions for different error classes.
• Keep tags accurate. Incorrect tags (e.g., tagging a React project as framework:vue) degrade result quality for you and pollute the network for others.
• Start specific, broaden if needed. If a highly specific tag combination returns no results, remove the version or the most niche tag and try again.