Using Semantic Tags

Semantic tags are how Spark understands the context of your query. They tell the recommendation engine not just what you're asking about, but which version, which framework, and what kind of task you're performing. Better tags mean better results.

Tag format

Tags follow a simple structure:

TYPE:NAME
TYPE:NAME:VERSION

TYPE identifies the category (language, framework, library, etc.)
NAME identifies the specific technology
VERSION (optional) narrows to a specific version

Common tag types

Language

Specify the programming language and optionally the runtime version.

--tag language:python:3.12
--tag language:javascript
--tag language:node:20
--tag language:typescript:5.4
--tag language:rust:1.77
--tag language:go:1.22

Framework

Specify the framework you're using.

--tag framework:react:18
--tag framework:express:4
--tag framework:django:5
--tag framework:nextjs:14
--tag framework:fastapi:0.110
--tag framework:rails:7

Library

Specify a particular package or library.

--tag library:pandas:2.1
--tag library:axios:1.6
--tag library:prisma:5
--tag library:zod:3.22
--tag library:pydantic:2.6

Task type

Describe what you're trying to do.

--tag task_type:bug_fix
--tag task_type:integration
--tag task_type:migration
--tag task_type:performance
--tag task_type:configuration
--tag task_type:testing
--tag task_type:deployment

Domain

Indicate the problem domain.

--tag domain:web
--tag domain:api
--tag domain:cli
--tag domain:database
--tag domain:auth
--tag domain:devops

Error type

Include the specific error class for debugging queries.

--tag error_type:TypeError
--tag error_type:ModuleNotFoundError
--tag error_type:ERR_MODULE_NOT_FOUND
--tag error_type:CORS
--tag error_type:ConnectionRefused

Version specificity

Versions support three levels of specificity. Spark matches at the level you provide, so more specific versions give more targeted results:

Tag	Matches
`language:python`	Any Python version
`language:python:3`	Python 3.x
`language:python:3.12`	Python 3.12.x
`language:python:3.12.1`	Python 3.12.1 specifically

💡

For most queries, MAJOR.MINOR is the right level of specificity. Using framework:react:18 will match solutions for React 18.0, 18.2, 18.3, etc. Use patch versions only when a specific patch introduced or fixed the behavior you're asking about.

Combining multiple tags

Use multiple --tag flags to narrow your query to a precise intersection:

spark query "hydration mismatch error in production" \
  --tag language:typescript \
  --tag framework:react:18 \
  --tag framework:nextjs:14 \
  --tag task_type:bug_fix \
  --pretty

This query says: "I need a bug fix for a hydration mismatch in a TypeScript project using React 18 and Next.js 14." The recommendation engine will prioritize solutions tagged with the same combination.

XML format alternative

For programmatic use or when you need to pass structured tag data, Spark supports an XML format:

spark query "memory leak in pandas groupby" \
  --tag language:python:3.12 \
  --tag library:pandas:2.1 \
  --tag task_type:bug_fix \
  --pretty

Both formats produce the same result. The CLI shorthand (--tag) is more convenient for interactive use; the XML format is useful in scripts or when integrating Spark into other tools.

How tags improve recommendation quality

Tags serve three functions in the recommendation engine:

Filtering. Results are narrowed to solutions that match your tags. A query with --tag framework:express:5 won't return solutions for Express 4 unless they explicitly apply to both versions.
Ranking. When multiple solutions match, tag overlap boosts relevance. A solution tagged with framework:express:5 AND task_type:migration will rank higher for a query with both those tags than a solution with only one.
Version awareness. The engine understands that framework:react:18 is different from framework:react:17. Breaking changes, new APIs, and deprecations are version-specific — tags ensure you get advice that applies to the version you're actually using.

⚠️

Queries without tags still work, but they return broader results. If your first query doesn't return relevant results, adding tags is the single most effective way to improve them.

Tagging when sharing solutions

Tags are just as important when sharing as when querying. When you share a solution, add tags so future developers can find it:

spark share abc123 \
  --title "Fix React 18 hydration mismatch with dynamic content" \
  --content "..." \
  --tag framework:react:18 \
  --tag framework:nextjs:14 \
  --tag task_type:bug_fix \
  --tag error_type:HydrationError

Be specific with your tags. A solution tagged framework:react:18 and error_type:HydrationError is far more discoverable than one tagged only language:javascript.

Next steps

Sharing Solutions — how to contribute your solutions to the network
Best Practices — tips for getting the most out of Spark

Tutorial: Integrate a Public API Sharing Solutions