Revit shared parameters: what they are, how to create them, the .txt file, title blocks and the errors that keep coming back

The real difference is the GUID. Revit recognizes a shared parameter by its GUID, not its name. That's why the same parameter can live in a hundred families and ten projects and Revit knows it's the same data. A family parameter, by contrast, exists only inside that family.

When to use each:

• Family: to drive internal geometry, such as a width or angle nobody will schedule.
• Project: for data that's only scheduled or filtered in that one project.
• Shared: for anything that gets tagged, scheduled across projects, shown in a title block or read by a plugin.

Shared parameters live in a text file that stores each one's name, GUID, data type and group. The file's own header warns against editing it by hand.

Shared parameter file location: any folder. Each user picks the file under Manage › Shared Parameters, and Revit remembers that path on their machine.

What few people know: once a shared parameter is in a project or a family, its definition is stored there. The file is only needed to add new parameters. If the file is lost, projects keep working, and a parameter can be recovered by exporting it from a family that has it, with the same GUID. What you must never do is create it again with the same name.

Rules for an organized firm:

• One master file, in a network folder that's read-only for everyone except its owner.
• Groups by purpose, such as Sheets, Structural or Quantities.
• Names with a firm prefix, so they're never confused with manufacturer or client parameters.
• Never delete and recreate a parameter: the new one would have a different GUID.

Create it in the file:

1. Manage › Shared Parameters.
2. Browse to the file or create a new one.
3. Create a group, or pick an existing one.
4. Create the parameter: name, data type, such as text, number, length or yes/no, and a tooltip explaining what it's for.

Add it to the project:

1. Manage › Project Parameters › Add.
2. Choose Shared parameter and select it from the file.
3. Decide whether it's instance or type, which Properties group it appears under, and which categories it applies to.

Add it to a family: in the Family Editor, Family Types › New Parameter › Shared parameter. If the family and project use the same shared parameter, Revit treats them as one when the family loads.

• Schedules. A shared parameter shows up in the field list of schedules for its categories, and can be edited from the schedule. If you need to fill it from Excel, we cover it in exporting Revit schedules to Excel and back.
• Tags. In the tag family, the label is built from the same shared parameter. The tag then reads the value from any element that has it.
• Title blocks. To show firm-specific data in the title block, such as the engineer's license number or the discipline, create a shared parameter, add it to the project on the Sheets category and use it in the title block label. We cover it in Revit revisions and signatures on multiple sheets.

• Shared parameter not showing in the schedule. It's a family parameter, not a shared one; or it isn't bound to that schedule's category.
• The tag shows nothing. The element doesn't have the parameter: its family doesn't include it, or the project parameter isn't bound to its category.
• The tag shows a question mark. The parameter exists but is empty on that element.
• Two parameters with the same name. Someone created another one with the same name in a different file: it has a different GUID and Revit treats them as different data. The schedule reads one, the tag reads the other, and the values don't match.
• I can't find the parameter when loading it. Revit is pointing to a different shared parameter file; check the path under Manage › Shared Parameters.
• Instance and type mixed up. If the value should change per element but was created as a type parameter, changing it changes every element of that type.

• One owner for the master file, and a log of every new parameter: what it's for, who asked for it, which categories it goes on.
• Templates with the parameters preloaded, so every project starts the same way.
• Families reviewed before they enter the library: they should use the master file's parameters, not copies.
• Regular audits of projects to find duplicate or orphaned parameters. It's part of what a BIM audit checks.

• Loading the firm's parameters in bulk into many projects and families at once, with their categories and groups.
• Finding duplicates: the same name with a different GUID, across every model in a project.
• Filling values from Excel and writing them back, without touching each element.
• Checking families before they enter the library.

The core, with the Revit API, is short:

// Add a text shared parameter to the Sheets category
DefinitionFile file = app.OpenSharedParameterFile();
DefinitionGroup group = file.Groups.get_Item("Sheets") ?? file.Groups.Create("Sheets");
Definition def = group.Definitions.get_Item("FIRM_LicenseNumber")
    ?? group.Definitions.Create(new ExternalDefinitionCreationOptions("FIRM_LicenseNumber", SpecTypeId.String.Text));

CategorySet categories = app.Create.NewCategorySet();
categories.Insert(doc.Settings.Categories.get_Item(BuiltInCategory.OST_Sheets));

using (var t = new Transaction(doc, "Shared parameter"))
{
    t.Start();
    doc.ParameterBindings.Insert(def, app.Create.NewInstanceBinding(categories), GroupTypeId.IdentityData);
    t.Commit();
}

If you want the Autodesk APIs from the ground up, start with Revit and Civil 3D add-in development.