Learn about Webel's comprehensive SysMLv2 Workshop Seminar course!

Webel now has a SysMLv2 Online Self-Study course with self-test Quizzes!

Learn about the Webel Q&A     online self-testing system for SysML v2/v1

Learn about the Webel SysMLv2 Ports audio mixer case study course module!

Webel Best Practice

This it the tag/keyword search page for Webel Best Practice. For a more collated list of best practice tips for Unified Modeling Language (UML^®) and Systems Modeling Language v1 (SysML^®) with explanations please visit also Webel's Best Practice policy notes for MBSE with SysMLv1/UML2 and the MagicDraw/Cameo tools.

Webel: SysMLv2: Part usages don't replace part definitions and there is no good reason to not use part definitions as the primary system modelling mechanism

Webel: SysMLv2: For a quantity «attribute» prefer feature typing by an ISQ «attribute def» over subsetting of an ISQ «attribute» (the names of which don't cover all cases anyway so eventually you'll need to use the feature typing approach).

SysMLv2: Webel Best Practice: Avoid flow connections without a payload. From a systems engineering perspective it's best to identify exchange items as early as possible and use them as soon as possible.

Webel: SysMLv2: Cameo: TIP: Whilst long KerML expressions may be convenient in code they don't always display well in Views. Consider Divide & Conquer strategies for breaking them up into smaller expressions carried by related elements.

Webel Best Practice: SysMLv2: Recommend indeed use the optional derived declaration for attributes with derived expression values for better traceability and for clearer display as /derived when feature values are not shown.

Webel Best Practice: SysMLv2: "Trust the Type": If using parameter = shorthand to provide a feature always also include the :Type in the declaration (which is an implied redefinition) - and even if it's a bit tedious and a bit WET.

Webel Best Practice: SysMLv2: "Trust the Type": If redefining a port or parameter to provide a "clean" connection end target always also include the :Type in the redefinition declaration - and even if it's a bit tedious and a bit WET.

Webel Best Practice: SysMLv2: Prefer graphically clearer explicit binding connectors from/to boundary ports over = binding shorthand (and even if = shorthand binding is convenient in code)

Webel Best Practice: SysMLv2: CAVEAT: Ports: Using Webel i/o directed feature naming may not display meaningfully with SysMLv2 ~conjugated ports. Consider instead one character feature name and still "Trust the Type" to communicate the feature role.

Webel Best Practice: SysMLv2: PortDefinition naming: DO NOT include the word 'Port'! Use prefix 'P_Role' OR for ports with directed features for flows consider 'F_Thing' or 'F_Stuff' where Thing or Stuff indicates a flowing discrete packet or substance.

Webel Best Practice: SysMLv2: "Trust the Type" and use short or acronym feature names instead of verbose feature name that just repeat the Type name but as lowerCase! ANTIPATTERN: veryLongName:VeryLongName

Webel Best Practice: SysMLv2: Prefer Views that DO NOT rely on specific packaging structures EXCEPT for dedicated package overview diagrams (and then prefer just list members in a compartment). Use of package symbols for GRAPHICAL containment can break!

SysMLv2: Webel: The challenge of the twice-performed action (or twice exhibited state) when combining "logical" functional analysis breakdown using performed actions with allocations to "physical" components

Webel Best Practice: “There is nothing worse than a sharp image of a fuzzy concept.” (Ansell Adams, photographer)

SysMLv2: Webel Best Practice: Prefer use performed actions and exhibited states as the primary mechanism for "logical" layer/zone systems engineering functional analysis breakdown (not SysMLv2 allocations).

SysMLv2: Webel Best Practice: If you have as many allocation definitions as allocation usages in your final model you might not be using them effectively!

SysMLv2: Webel Best Practice: An allocation definition should be of a specific "nature" (possibly related to a formal systems engineering methodology, and optionally with the "nature" further distilled using custom Metadata).

Webel Best Practice: SysMLv2: "Trust the Type": When redefining a subject (within any element kind) ALWAYS also include the :Type in the redefinition declaration (even if it's a bit tedious and a bit WET).

Webel: SysMLv2: Cameo: Modelling Best Practice: Links to examples of _DELIBERATELY_ very large Views (diagrams) that are candidates for "Divide & Conquer" strategies. Some linked examples are AntiPatterns!

Webel Best Practice: SysMLv2: States: Instead of an "empty" entry action (that does nothing) with a succession to an initial state prefer a start:StateAction with a transition to the initial state EXCEPT where conditional successions are needed.

Webel: SysMLv2: Modelling OPTION: Links to examples of heavily compartment-oriented views (compare with relationship-oriented views). Often combined with the Symbol Style option to display inherited features. Consider for non-SysMLv2 fluent stakeholders.

Webel Best Practice: SysMLv2: "Trust the Type" functional analysis: When referencing a performed action or exhibited state ALWAYS also include the :Type in the declaration (even if it's a bit tedious and a bit WET). Helps avoid also verbose usage names!

Webel Best Practice: SysMLv2: Prefer transition (not succession) from start:StateAction

Webel: SysMLv2: Modelling: When parameters are bound using = binding without flow connectors the "pin" boundary symbols end up "floating". If you instead list all parameters in a compartment do still also show any actually connected ones as "pin" symbols.

Webel: SysMLv2: OPTION: If using = binding shorthand (instead of binding connectors) from/to context boundary parameters try listing the parameters in compartments with their bound values (rather than as parameter boundary "pin" symbols). Saves space!

Webel Best Practice: SysMLv2: Prefer graphically clearer explicit binding connectors from/to context boundary parameters over parameter = binding shorthand (and even if = shorthand binding is convenient in code)

Webel Best Practice: SysMLv2: Avoid naming features after their owner where it is clear what owns them.

Webel Best Practice: SysMLv2: Where port usages aren't connected just list them in compartments (do not show them as port boundary symbols).

Webel Best Practice: SysMLv2: "Trust the Type" feature name hiding. In many Views, there is no benefit, at all, in showing feature names (especially if they are needlessly verbose and just repeat the Type name but lowerCase)

Webel Best Practice: SysMLv2: OPTION: Use Webel convention role-based parameter names with actions for indicating transformations together with Webel display conventions (not any verbose parameter names). To find out how attend the Webel SysMLv2 course!

Webel Best Practice: SysMLv2: VERY STRONG RECOMMENDATION: Prefer Webel "Trust the Type" i/o parameter naming and Webel display conventions over verbose parameter names. To find out how attend the Webel SysMLv2 course!

Webel: SysMLv2: IMPORTANT! Specification documents and the namings used in their supporting examples have a specific purpose and the examples play specific roles. They are NOT tutorials on how to model practically in a specific tool on real projects!!!

Webel Best Practice: SysMLv2: VERY STRONG RECOMMENDATION: Prefer Webel "Trust the Type" i/o port naming and Webel display conventions over verbose port usage names and verbose directed feature names. To find out how attend the Webel SysMLv2 course!

Webel: SysMLv2: Cameo: Modelling Best Practice: EITHER display a feature in a compartment (preferred for non-structured) OR display the symbol of the feature (may be necessary if structured) but NOT both (except for special educational illustration).

Webel: SysMLv2: Terminology: in some Webel slides and diagrams the little rectangular parameter boundary symbols with directed feature arrows are INFORMALLY called "pins" (borrowing terminology from SysMLv1) but this is NOT a formal SysMLv2 term.

Webel: SysMLv2: Cameo: Modelling Best Practice: For parameters prefer compartment view (where available) over boundary symbols UNLESS you need to show relationships from the symbols OR have special reasons (such as educational illustration).

Webel: SysMLv2: Cameo: TIP: You can move parameter symbols (the little boxes with arrows) around the boundary of their owner's symbol to save space and improve readability. Parameters displayed on the left (default Cameo layout) take up a lot of space.

Webel: SysMLv2: Cameo: Modelling Best Practice: For non-structured features prefer compartment views with feature values over symbols UNLESS you need to show relationships from feature symbols OR have special reasons (such as educational illustration).

Webel: SysMLv2: Cameo: Modelling Best Practice: Adopt a tight packing strategy leveraging the Cameo grid (but DO NOT obscure the ends of relationship arrow symbols).

Webel: SysMLv2: Cameo: Modelling Best Practice: Links to examples of appropriate and effective use of outline colours for special highlighting with specializations and hierarchies. BUT does not always work well if overdone!

Webel: SysMLv2: Prefer member ownership relationship symbols over Package symbol member containment (which can break if you change the packaging). [POSSIBLE EXCEPTION: Modelling readonly library packages.]

Dr Darren's SysMLv2 dream: Just 'att' instead of 'attribute' as code keyword.

Webel's Best Practice policy notes for MBSE with SysMLv2 and the Cameo (CATIA Magic) tools

Keywords

Keywords

Looking for the Webel Best Practices for the newer SysMLv2?

Webel Best Practice: SysMLv2: Cameo: Where the aim is show details of structured attributes and/or to show relationships from attributes (such as for educational reasons) they may be displayed as symbols. But in general, prefer the compartments display.

Webel Best Practice: SysMLv2: Cameo: TIP: Prefer show EITHER a specialization relationship from a symbol OR show the specialization in the symbol header using Display Styles -> Show Specialization. Prefer NOT show both modes in one View.

Webel Best Practice: SysMLv2: STRONGLY recommend black on white style with colours (best only for symbol outlines) only used for special highlighting. [READ FOR INSTRUCTIONS for b/w in Cameo SysMLv2]

Webel SysMv2 modelling convention for tutorials and training. Metaclasses and elements from the KerML and SysMLv2 machinery are white on black or white on strong "darker" colours (blue, magenta, purple etc.) to distinguish them from user model elements

SysMLv1: Webel strongly recommends a looser, more "logical" modelling strategy over modelling practices with strong coupling to "physical" ownership. Many of the Webel Best Practices support this approach.

SysMLv1: TIP: If a symbol for an element that appears on a Block Definition Diagram or a Package Diagram is not directly within the namespace of the context of that Diagram indicate the ownership using display options or one of the containment devices

Webel: Mathematica: CONVENTION: A 'type$' indicator for an '$opt$' or '$arg$' is for documentation only. It may use a "pattern helper", a human-friendly String, or a SysML-similar short-hand type representation. It need not correspond to a valid Pattern.

Webel: Mathematica: CONVENTION: A '$Q$' in a function variant name indicates that it is a variant where every argument is strictly either a Quantity or dimensionless Real. Compare with '$SI$' functions.

Webel: Mathematica: CONVENTION: An '$E$' or '$EQ$' in a function name indicates that it is symbolic (takes Blank expression arguments), but the absence of '$E$' or '$EQ$' does not necessarily imply that it does not take Blank arguments.

Webel: SysML4Mathematica: An '@~' prefix in a @pseudo function (OpaqueBehavior or Activity) represents a cast from any expression to a Type. Example: '@~OpenerView' casts from any expression to an OpenerView. '@Type~' casts from a specific Type.

Webel: Mathematica: CONVENTION: An '$SI$' in a function variant name indicates that all arguments are SI Real convention (no Quantity arguments with units). An '$SI$' function can also be used to generate '$C$' compiled function variants.

Webel: Mathematica: CONVENTION: A '$C$' in a function name indicates that it is a compiled variant. Typically it is compiled from an '$E$' symbolic function or an '$SI$' Real convention function.

Webel: Mathematica: CONVENTION: An '$E$' in a function name indicates that it is symbolic (takes Blank expression arguments). An '$E$' function can also be used with Quantity inputs and can be used to generate '$C$' compiled function variants.

Webel: Mathematica: CONVENTION: A '$EQ$' in a function name indicates that it is a symbolic equation (with LHS == RHS). An '$EQ$ function can be used in combination with 'sym$' markup to create human-friendly formatted equations.

Webel: Mathematica: CONVENTION: Entity "field definers" are prefixed with '$e$[pac]' (where '[pac]' is a nickname for a package or logical grouping) and carry String field names. EntityStore functions are prefixed with 'e$[pac]'.

Webel: Mathematica: Packages that import the Webel HelpF` package (but not MTools and the Webel HelpM` package) should use the 'usageF' function for ::usage String generation (rather than the 'docF' and 'docV' functions) and an AOR Map.

Webel: Mathematica: CONVENTION: A '$sig$f$' prefix indicates a String signature helper for a function (or for a "method" of an MTools class or a Webel Abstract Data Type (ADT) pseudo class).

Webel: Mathematica: CONVENTION: A '$doc$' prefix indicates a formatted documentation String helper. A '$doc$arg$' is for an argument, a '$doc$opt$' is for an option. A '$doc$ String may be used to create ::usage documentation via docF.

Webel: Mathematica: CONVENTION: A ‘$pac$’ String helper variable is used to capture the fully qualified String name of every package. Useful for quick '$pac' argument provision for search functions and for DEVEL package load echoes.

Webel: Mathematica: CONVENTION: A 'z$' prefix may be used to indicate a Private` function or expression within a package or a "private" method of an MTools class or Webel Abstract Data Type (ADT) stateless pseudo class.

Webel: Mathematica: CONVENTION: The Stereotype keyword «functional» indicates a "pseudo functional" representation of functional in SysML. There are limits to representation of functional programming in SysML, but it can be informative and is worth doing.

Webel: Mathematica: CONVENTION: A '$t$' prefix indicates a String help holder with a "pseudo type" indicator (for human friendly documentation only). Used by the Doc`, HelpF`, and HelpO` packages.

Webel: Mathematica: CONVENTION: A function's description (but not its signature, arguments, or options) may be captured as an '$info$f$' Stringhelp holder for use by the Doc` package for ::usage generation and the HelpF`& HelpO` help registry packages.

Webel: Mathematica: A help Rule 'rule$opt$' for an '$opt$' (option) accepts keys: '$k$help' (required), '$k$def' (required), and optional '$k$warn', '$k$tip', '$k$lab' (a label), '$k$type' (indicator only), '$k$mult' (SysML multiplicity), and '$k$pat'.

Webel: Mathematica: A help Rule 'rule$arg' for an '$arg$' (argument) accepts keys: '$k$help' (required), '$k$def' (required if $k$req = True not given), '$k$req' (True if $k$def not given), '$k$warn', '$k$tip', '$k$lab', '$k$type', '$k$mult' and '$k$pat'

Webel: Mathematica: CONVENTION: An '$opt$' (option) or '$arg$ (argument) help holder may be have an associated (typically short) '$lab$opt$' or '$lab$arg$' label help holder for use in GUIs and views.

Webel: Mathematica: CONVENTION: Where keys of Associations are Strings they are encapsulated as variables prefixed with '$k$' (promotes DRY and has many advantages, such as IDE prompting). Direct use of "Strings" as keys is WET and strongly discouraged!

Webel: Mathematica: CONVENTION: "pattern helpers" (which are not themselves Patterns) use the prefix '$pat$. Encapsulated Patterns use a 'pat$' prefix, and may use a '$pat$' pattern helper (such as an Alternatives).

Webel: Mathematica: CONVENTION: Argument help holders use a String variable with the prefix '$arg$', a related '$info$arg$' String, a 'def$arg$' default value expression and/or 'req$arg$', and optional '$warn$arg$', '$tip$arg$, '$lab$arg$', 'type$arg$'..

Webel: SysML/MBSE: Suggest don't fuss about ownership (containment) too much early on. Focus on "logical" modelling, values, flows, relationships between elements. Suggest perform regular separate modelling "housekeeping" sweeps to deal with ownership.

SysMLv1: Webel often uses Model packages for most modelling and reserves Package for code-like elements, OpaqueBehavior sub-libraries, instances, and elements reverse-engineered from code. But there are no hard and fast rules about Package vs Model.

SysML: HOWTO Represent a person as an external block-based SysML «actor» in one lower context and as an internal participating «person» in another higher context, with traceability. For modelling systems of systems in a team with many modellers.

Dr Darren says: 'You can't obtain the optimum benefit of graphical engineering with SysML without becoming mindful of the cognitive and artistic aspects of graphical modelling. The "Zen of SysML" matters!' Just like an elegant electronics device design.

Dr Darren's strategies for effectively introducing SysML for MBSE on your projects and the importance of extracting incremental benefit from the powerful SysML language and MBSE tools

Webel SE: pragmatic tool-friendly functional analysis: 2-level drill-down from a single Use Case via a «scenario» Activity with allocation to «logical» subsystems first then crossing to the «design» Blocks zone.

Gallery

Tutorial

[STUB] TRAIL: Webel's ultimate guide to simplified yet adequate pragmatic systems engineering with functional analysis in SysMLv1 for smaller scale MBSE projects in the MagicDraw/Cameo/CATIA Magic tools

Section

Slide kind

SysML Activity Diagram

SysML Block Definition Diagram (BDD)

SysML Internal Block Diagram (IBD)

SysML Package Diagram

SysML UseCase Diagram

An Open Letter to LinkedIn SysML/MBSE groups from Dr Darren: "But, but, but, that SysML Diagrams doesn't show [insert pet systems engineering principle here]". It doesn't have to! It just has to show (or teach) something useful with SysML in a SysML tool!

SysMLv1: TIP: You can strengthen the ill-defined semantics of Property 'aggregation' (an AggregationKind) by applying custom Stereotypes to a Property, documented with its intended use. Not perfect, but better than not. EXAMPLE: «assembled»

SysML: Syntax ain't Semantics: FUN CHALLENGE: SysMLv1 block property aggregation: 'The tornado chaser plane "has" a chaser car "with" a chaser team.'

Webel Parsing Analysis for SysML: "Snippet trumps Requirement": A SysML Requirement element is just another model element that is elicited IN PARALLEL WITH other elements that a text description mentions in any way as being involved with or related to it.

The Webel recipe for pragramatic SE with SysML adopts the MagicDraw/Cameo tool friendly approach of using a SystemContext as 'subject' of top-level UseCases (although using a System as 'subject' can also be used).

The Webel recipe for pragramatic SE with SysML omits many of the concerns addressed by fully-fledged systems engineering frameworks. Many of these can be partially addressed by using custom Stereotypes for extraction using query view tables.

Webel: SysML: SE: The custom stereotype keyword «design» covers elements involved with BOTH design and/or implementation aspects in the 'solution' zone. (In more comprehensive SE methodologies design and implementation are often treated separately.)

Webel: SysML: SE: Stereotype keyword convention: BY DEFINITION HERE «blackbox» and «whitebox» refer specifically to the 'problem' zone and NEVER the 'solution' zone (as opposed to more general uses of the terms 'black-box' and 'white-box').

[STUB] TRAIL: Webel's ultimate guide to simplified yet adequate pragmatic systems engineering with functional analysis in SysMLv1 for smaller scale MBSE projects in the MagicDraw/Cameo/CATIA Magic tools

Jump to first slide

Webel SE: pragmatic tool-friendly functional analysis: 2-level drill-down from a single Use Case via a «scenario» Activity with allocation to «logical» subsystems first then crossing to the «design» Blocks zone.

Sections

Webel: SysML: SE: Naming convention: «whitebox»: A '$' prefix indicates a «logical» system, «logical» subsystem (aka conceptual subsystem) or «logical» handler Block (which is a more specific form of «logical» subsystems Block).

Webel: SysML: SE: Naming convention: '0' used for a Package/Model name indicates a zone dedicated to a formal systems engineering breakdown (functional analysis, blackbox, whitebox, logical vs design or implementation etc.)

Webel: SysML: Use concise Package and Model naming to provide "context aware" owner paths that reflect a systems engineering strategy. Extremely so-called "human friendly" verbose Package/Model names with spaces DO NOT make the model easier to understand!

Webel: Dr Darren says: "Many aspects of older Document-Intensive Systems Engineering methodologies and the reporting obligations they impose on their users were intended to address problems that simply DO NOT EXIST ANYMORE with modern MBSE with SysML!"

Webel: SysML: "Really long human friendly element names with spaces make my diagrams easier to read". Dr Darren says "No they don't! Prefer code-like naming (or anonymous for typed elements) wherever possible. Use custom tagged values for other names!"

Webel: SysMLv1: Recommend using Block Definition Diagrams as associative, graphical engineering "scratchpads" FOR YOU; Use Internal Block Diagrams as the main presentation diagrams for your engineering colleagues and other stakeholders!

SysML: MagicDraw/Cameo: Use query view tables, matrices, and maps, use them a lot! They help communicate well with other stakeholders. Learn how to use the Generic Table diagram type, custom relations, Simple Navigation & Metachain Navigation (expert)!

Webel: SysMLv1: TIP: Use semantically meaningful Association names and/or custom Stereotypes where applicable. They can also often be used as pseudo OWL/RDF semantic triples. But don't use Association names where an ItemFlow can capture an exchange item!

Webel: SysML: Heard of "follow the money"? In MBSE we "follow the flows"! Identify requests, data packets, messages, signals early on and use ItemFlow as often as you can wherever you can! Adopt a signal processing mindset throughout (systems thinking).

Webel: SysMLv1: Overview of annotated Diagram Slides and Note pages related to general high level SysML modelling principles (some specific to MagicDraw/Cameo). Recommended reading for all Webel SysML/MBSE course attendees.

Webel: SysML/UML: Dr Darren explains HOWTO use concise 'i'/'o' (input/output) Pin and Parameter naming conventions to promote a signal processing mindset in Activity Diagrams. And HOWTO get them compact.

Webel: SysML: TIP: Try "reverse" time ordered effect-from-cause Dependencies. Because it's harder to depend on something that does not already exist!

Webel: SysMLv1: Dr Darren for LinkedIn: On "Trusting The Type" and avoiding unnecessary verbose repetitive Property names ... unless you really, really need them and really do have reasons to use them, and then only use concise role indicators anyway!

TIP: SysMLv1: MagicDraw/Cameo: Activity Diagrams: Consider using the Pin display mode 'Name And Type Labels Inside' for 'Position of Labels'. Dr Darren swears by it!

Webel: SysML/UML: Some example diagrams show extremely fine-grained and trivial examples purely for educational and capability demonstration purposes (not as practical recommendations for real-world projects). You can sometimes just use code in SysML.

Webel: Psy/MPsy: Psychrometrics for Mathematica: Convention: Option variable names are prefixed with '$opt$psy'

Webel: Mathematica: CONVENTION: Option help holders use a String variable with the prefix '$opt$', a related '$info$opt$' String, a 'def$opt$' default value expression, and optional '$warn$opt$', '$tip$opt$', '$lab$opt$', and 'type$opt$' indicator ...

TIP: Webel: SysML/UML: On the boundary of symbols for ConstraintParameters on a ConstraintProperty (ConstraintBlock usage) symbol in Parametric Diagrams use any placement or "ordering" of ConstraintParameter symbols that works for the diagram!

TIP: Webel: SysML/UML: On the boundary of Action symbols in Activity Diagrams use any placement or "ordering" of Parameter symbols that works for the diagram. Ignore the Parameter ordering of Operation and Behavior signatures completely!

SysML Parametrics: You can use custom stereotypes keywords «i» and «o» on constraint parameters to indicate their intended use (causality) as (i)nputs and (o)utputs on ConstraintBlocks

On the Webel Best Practice modelling tips for SysML v2/v1. If you want to model the Webel way, use them, if you don't, ignore them. They are ONLY offered as options and graphical modelling paradigms and idioms for you to consider.

Webel: On going beyond SysML (and UML) with additional modelling practices, policies, and additional semantics

Webel: SysML: TIP: CONVENTION (default policy suggestion): Use reverse time ordering for Dependency, reserve Usage, PackageImport, ElementImport for software dependencies

Webel: MagicDraw/Cameo: UML/SysML: TIP: Activity Diagrams, StateMachine Diagrams, and port-based IBDs: Keep it loose initially with oblique (no break) paths, then square it up with rectangular paths at the very end

Webel: SysMLv1.x: TIP: The name and documentation of a ValueType can indicate and specify more than just the unit and quantity kind. Example: A ClockFrequency may document how the frequency is measured. Example: WeightOnEarth.

Mathematica: The Webel Units` package has Quantity variables for frequently used units using a naming convention 'unit$[Symbol]' or 'unit[DescriptiveName]' or unit[Acronym], each with a corresponding '$unit...' for the units identifier String(s).

Webel electronics modelling recipe for SysML: Diagrams can be made less verbose by using stereotype icon shape display mode, by not showing names and types on obvious Ports, by hiding context-specific values, and by omitting {net} tagged values.

Webel: SysML: Electronics modelling: TIP: Use a custom Connector stereotype '<>' with the keyword '<>' to carry a 'net' property. (Use of punctuation in Stereotype names is not usually recommended and the keyword is not usually displayed.)

TRAIL: SysMLv1: Theory and best practices for the Webel Parsing Analysis recipe for SysMLv1.6+

Jump to first slide

Top-level Package/Model organisation for the Source Input Zone

Sections

SysML: Naming: You may include Block, ValueType, and Signal names in the names of Behaviors (such as Activities) as long as this does not undermine the principles of functional analysis and allocation.

UML/SysML: In Internal Block Diagrams: If you have a Port with a name that indicates a unique role AND and if there is an ItemFlow on a Connector that implies or suggests the Type of the Port, consider hiding the Type on the Port symbol.

SysML+SysPhS: Flows: If you intend to use a Classifier to type the itemProperty of an ItemFlow on a Connector for a physical interaction you MUST use a Block (not a ValueType or Signal) so your can extend ConservedQuantityKind.

SysML: Flows: If you use a Signal to type the itemProperty of an ItemFlow on a Connector, care must be take in how you create the Property or you might get an unwanted signal Reception on the owning context Block.

SysML: Whether you use a Block, ValueType, or Signal to represent something that flows (and can be applied to an ItemFlow) depends on what you want to achieve. If you want to indicate something structured with value properties with Units use a Block.

Progressively "exporting" internal Ports of usages of Blocks to the boundary of their using Block may seem like a bit of extra work, but it means you can progressively develop with clean black box views without the Connectors crossing Block boundaries.

In the Webel terminology for a basic control loop there is an 'aim' value (controlled via an actuator) and a 'got' value (a value read from a sensor). The 'got' value is NOT necessarily exactly the same as the actual physical value.

SysML-1.6/1.7: You can introduce a custom (user-defined) stereotype keyword «item» to indicate Properties that are to be used as "packets" for ItemFlows on Connectors. (SysMLv2 will have a formal way of treating such items/packets.)

Webel: SysML: DO NOT sacrifice modelling naming conventions for the mere sake of carrying organisation-specific names! Instead use tagged values of custom stereotypes as metadata to carry alternative names in parallel with systematic model element names.

SysML/SysPhS-1.1: Anonymous Property or Action names may not be an option if: You are exporting to Modelica or Simulink; You absolutely need names for generated query reports (such as generated Interface Control Documents).

Webel: In some SysML trails ValueType names with Unit indicator suffixes have been used for dimensional analysis and illustrative purposes. This practice is NOT otherwise recommended here. Instead just use consistent custom ValueTypes across your system!

SysML: When using Property::defaultValue and Property::redefinedValue to carry a "shadow hierarchy" of redefinitions across an entire system hierarchy, considering using a user-defined keyword such as «configuration» or «scenario» on each redefining Block

Webel: UML/SysML: Navigation: ALWAYS offer a way out of a diagram (usually up a hierarchy, but possibly across) using a navigable symbol (linked to a diagram) and/or a diagram symbol. Avoid "cul-de-sacs"! [But beware of shared package cross-dependencies]

Block naming: If you find you've got similar blocks named 'Thing' and 'Thing2' then 'Thing' is probably better renamed 'Thing1'

The use of an additional «port» keyword on a Port is usually redundant and causes clutter. The use of an additional «port» keyword on a basic Property is an obsolete trick. Please don't imitate it even if you see it in some specification sample diagrams!

Webel Best Practice: SysML/SysPhS: DO NOT use overlapping Connector lines from/to one Port (can be misunderstood as "summed" flow and/or physical node/fork/junction).

UML/SysML: A Boolean "state flag" attribute corresponding to a State can be useful for indicating states in some diagram types (but must be synchronised with Transitions to States carefully).

UML/SysML: During modelling it can really help to create little instance (object) diagrams as you go! This can also help communicate with non-SysML stakeholders.

UML/SysML: If you have a Boolean "state flag" attribute corresponding to a State you MUST set it on an 'entry' of the State, not on the 'effect' of a Transition into the State (otherwise with multiple incoming Transitions it could be WET and breaks SSoT).

Webel Twin Pattern: Convention: [MIGHT CHANGE]: A '*' prefix in a Property name of a «digital» @Block in a DigitalTwin model indicates a mapped block property, which must be typed by a non-digital «mappable» Block, and must have the «@» keyword applied.

WARNING: In natural language casual conversation one often hears people speaking of a digital twin "replicating" or "twinning" a physical entity. If you do it that way literally, you will NOT have anything to manage the control system loop!

Webel Twin Pattern: A PotentialPhysicalAsset is «digital», not «physical». It is used to acquire (an existing) or create (build, manifest, make) an «physical» ActualPhysicalAsset, which is a special case of «physical» PhysicalEntity.

Webel Twin Pattern: A DigitalTwin manages a control loop including a PhysicalEntity and a DigitalEntity (a.k.a. @Entity) that «replicates» it. It typically includes at least one Sensor and at least one Actuator.

Webel Twin Pattern: It is a DigitalEntity (a.k.a. @Entity) - not the DigitalTwin that owns it - that directly «replicates» geometrical, spatial, and material aspects (only) of a single PhysicalEntity.

Webel Twin Pattern: A DigitalTwin must model processes and the entities they act on separately.

Webel Twin Pattern: A «digital» DigitalEntity (a.k.a. @Entity) encapsulates strictly geometrical, spatial, and material aspects of a «physical» PhysicalEntity only. BY DEFINITION of this pattern it DOES NOT encapsulate processes!

Webel: Convention: [MIGHT CHANGE]: An '@' prefix in a DigitalTwin model indicates a «digital» Block that maps a non-digital «mappable» Block.

[HISTORICAL] SysML: Some users employed the ~ tilde prefix for a conjugated Port type long before it was introduced for ~InterfaceBlock and you MAY use it to name a regular Block that is not an ~InterfaceBlock

ARCHIVAL: Webel: SysML-1.7: WISHLIST: Constraint: A BindingConnector used for pure proxying MUST NOT be typed by an AssociationBlock by definition, because the associated information can be mis-appropriated to undermine the proxy equality!

SysML Parametrics: You can use custom stereotypes keywords «i» and «o» to indicate value properties that are intended to be used as (i)nputs and (o)utputs when bound to constraint parameters for SysML Parametrics

Computed category membership test values are sometimes adequate and can prevent Class/Block explosion. However, a dedicated Class/Block encapsulating a clear domain concept offers a clear documentation point and can carry other characterising features.

In professional applications of the Webel Parsing Analysis recipe for SysML, a robust reusable profile for «part»/«assembly»/«leaf» components is used, along with stereotypes keywords like «assembles» for indicating physical composition hierarchies.

In the Webel recipe for UML/SysML, the pattern of progressive redefinition of end Properties of Associations between progressively more specialised pairs of Blocks at the same level of abstraction is informally called a "redefinition ladder"

Do export your UML/SysML presentation diagrams (only, not every diagram) regularly as static images; it will help you develop diagrams that are better balanced and communicate well with stakeholders.

Webel Parsing Analysis diagrams do their job once - namely traceable elicitation of model elements - and are then only kept as a reference! The elicited model elements are then used elsewhere in the final model.

A "staging" BDD for defining the flows, ports, and item properties on blocks to be used in an IBD does not have to be a "work of art" if it is not intended as a final presentation diagram.

SysMLv1: Cameo: In Package Diagrams and Block Definition Diagrams use the owner indicator display option for Classifier symbol headers when indicating the owner (except where a containment operator suffices). The mode 'Below Element Name' is preferred.

Optionally suffix the "focus" BDD for a Block with '.bdd' so that it won't clash with a corresponding IBD on diagram export. This is not a SysMLv1 concern, it is purely a workflow concern. It has the slight disadvantage that BDD may "indicated" twice.

Webel: MagicDraw/Cameo: STRONGLY RECOMMEND: On EVERY project of ANY kind set the Environment Perspective to 'Full Featured' and check the Expert box, even if you are a "novice". For SysML use 'Full-Featured' not just 'System Engineer'!

Cameo/MagicDraw: The Classifier specification setting 'isAbstract' is (for reasons that beggar belief or engineering reason) not by default visible in the Element specification dialog. Enable expertise level 'All' (and for always everwhere).

ALL Model-Based Engineering: Just because you can't see a Feature or some other aspect of a SysML (or UML) Element in a tool on a symbol does NOT mean it does not exist in the underlying model (repository)! The model is not just what is DISPLAYED!

Rule #1: A UML or SysML Element in a tool is NOT just an Element symbol in a diagram! A Note is not an Element (compare with a Comment).

MagicDraw/Cameo: Keep most elements out of the top-level of a project (i.e. not directly under the project Root). Have one top-level index/content/package diagram.

Webel: Cameo: SysMLv1: TIP: Recommend maintain a basic black-and-white style file for starting new projects. Webel course attendees have access to a basic Webel.stl file (or clone and tune the 'OMG SysML style').

Webel: MagicDraw/Cameo: First recommended display style settings and project option steps for every SysML (and UML) project. [Includes TIP: DO NOT show the Diagram Name in the optional Diagram Info adornment, show it on the Diagram frame only]

Webel: SysMLv1.x: AVOID (where possible) SysML Unit names that are the same as unit symbols. Unit names SHOULD start with a lower case Latin alpha letter. Custom Unit names should be a single lower case word or lowerCamelCase.

If instances of Blocks “communicate” with each other use an Association between them.

Prefer not rename Properties when redefining unless indicating a clear change in role.

Webel: SysML: Always consider including an abstract (sometimes intermediate) base Block in your domain modelling Generalization hierarchy.

If using "French style" post-adjective naming in English use a trailing underscore after the noun and before the adjective or qualifier: Vin_rouge, Cable_digital. Can be combined with TLA acronyms: Player_DVD.

A common interpretation of composite Aggregation of a part property in SysML domain modelling is that if the owner Block is "destroyed" so is the child part property. Webel adopts these semantics always.

If an abstract Block or Class in a domain model has Associations to Blocks or Classes that are not also abstract, it's often a hint that you have not identified a correct abstraction layer.

SysML Blocks have lots of possible features and compartments, lots of capabilities, and are very powerful! But you don't have to use every aspect of a Block (or show every aspect in every diagram) at once on every project.

In SysML, unless you MUST use a DataType or PrimitiveType from an existing ModelLibrary or Profile, you SHOULD probably be using a ValueType, Enumeration ValueType, or SysML PrimitiveValueType instead so that it integrates with the value system of SysML.

Webel use editorial Sterotypes prefixed with ! and ? in and in CAPS in keywords such as: «!». «?», «!ERROR», «!ISSUE», «!CAUTION», «!WARNING», «!CAVEAT», etc.

SysMLv1: Associative BDDs are best used as staging diagrams for you the modeller (and SysML-fluent readers). IBDs usually make better presentations diagrams for a wider audience of general engineers and other stakeholders.

The name of a «testCase» Behavior may be verbose and may use natural language, but should always start with a Capital letter.

When satisfying a Requirement with a Block, you need to ask whether the Block (all instances) satisfies the Requirement or whether only a particular usage of the Block (such as a part property) Satisfies the Requirement!

Webel: If you must name your Ports or Pins, name them simply 'i', 'o', or 'io' (or 'oi') to indicate direction UNLESS you have to indicate a special role like 'iRole', 'oAuxiliary'. DO NOT use Port or Pin names like 'input', 'output', etc.

"Trust the Port or Pin Type!" - Often the name of the Type of an anonymous Port or Pin is completely sufficient to indicate its role, unless a clear indication of its direction or unique role is required.

UML/SysML: In Internal Block Diagrams: Consider hiding the name of a named Port or Property in a Diagram if its Type is sufficient to indicate its role.

In most Webel examples, the default is chosen to be 'out' if there is a single FlowProperty, so a Port with the type applied will act as a source. If an InterfaceBlock is used, then a Port typed by the conjugating ~InterfaceBlock will act as a sink.

Avoid mixing flow properties on the Type of a Port with directed features (operations and values); One distinguishes between "ports with flows" and "contract ports".

In general, the SysML DirectedFeature approach is more powerful and the notation is cleaner than UML provided/required Interfaces. Prefer SysML DirectedFeatures unless you have a really good reason to use Interfaces!

AVOID "mixed" functional (behavioral) allocation levels! DO NOT Allocate from Usage level (Action) to Definition level (Block) or from Definition level (Activity) to usage level (part Property) - even if formally permitted in SysML.

Use of 'this-that' with a hyphen in Connector names is admissable (where 'this' and 'that' indicate Connector ends or their types)

DO NOT use Connector names that are identical to the names of the Associations that type them!

DO NOT use Property names that are identical to the names of the Classifier (Class, DataType, Block, ValueType) that type them!

SysMLv1.x: ValueType naming: The Webel convention is 'UpperCamelCase' (a.k.a. PascalCase).

Webel: SysMLv1.x: AVOID (where possible) ValueType names that are the same as the name of units or unit symbols

Webel recommends (usually) display the header of a Package, Model, ModelLibrary, or Profile in the 'tab' (rather than 'top')

Webel: SysMLv1/UML: Prefer the Name Display Mode 'both' on CallBehaviorAction symbols (rather than 'Show Action Name', 'Show Behavior Name', or 'Show Both or Behavior Name')

Avoid punctuation in Property names (except when used to "quote text"). You can usually avoid underscores in Property names (even if they are used in the Type name) if you can "Trust the Type"!

TIP: UML/SysML: MagicDraw/Cameo: Consider showing the constraint parameter name and type label inside the small rectangular parameter symbol on SysML Parametric Diagrams. Dr Darren swears by it!

SysMLv1/UML: Prefer owner path indicators over Package containment operators (which are fragile).

Webel: "Trust the Metaclass or Stereotype" of an Element to indicate what type of element it is (you don't have to repeat it in the name)

Webel: SysML: You don't need to call every ConstraintBlock a 'SomethingEquation'

Webel: DO NOT name the Type (Block or InterfaceBlock) of a Port with a flow the same as the name of the 'Stuff' that flows through it; use the Webel 'F_Stuff' convention!

DO NOT use spaces in Property names or Class/Block names! If you want to communicate familiar names of elements within an organisation use a custom stereotype and tagged values (such as 'aka')!

FlowProperty naming. Use anonymous or just 'i' for in, 'o' for out, and 'io' (or 'oi') for inout. "Trust the Type". For conjugation ~InterfaceBlock use 'o' for in, 'i' for out, and 'io' (or 'oi') for inout.

TIP: MagicDraw/Cameo: Consider showing the Port name and type label inside the Port symbol! CAVEAT: This loses the direction indicators on Ports typed by Blocks with flow properties (but is fine if ItemFlows show the direction, or for "contract ports").

Webel: SysMLv1: Prefer not show Port symbols on the boundary of Block symbols in BDDs, just list them in compartments. One can't connect them in a BDD anyway. Recommend only show Port symbols in IBDs.

DO NOT name ports with first letter capital (like 'Port'), DO NOT name ports 'port' (except for educational illustration), and DO NOT use port names that do not indicate a role.

MagicDraw/Cameo tool support for Association composition "trees" is not good, and they end up being fiddly to maintain (and they can also cause issues for InformationFlows). Avoid them!

As an alternative to composition Association "trees" consider instead using symbol resize to visually "bracket" composed items (can however be a bit fiddly).

Webel suggests using a verbose 'name' for leaf (child) Requirements but NO 'text' to prevent Single Source of Truth issues and for improved callout vs relationships (but this might not always work when syncing with external requirements management tools)

Webel: SysMLv1/UML: MagicDraw/Cameo: AVOID the the vendor-specific «useCaseModel» stereotype for Model packages, it leads to confusion with the rectangular 'subject' notation

SysML: Webel: "Trust the Type!" - Often the name of the Type of an anonymous Property or instance-level element is completely sufficient to indicate its role - unless multiple Properties of the same Type have different roles within the same owner context!

SysMLv1: When using model queries (such as tables) for compliance with some older systems engineering docs you may not always be able to use anonymous Property names and anonymous instance level element names. Or try the owner context or the ID!

In SysML diagrams, showing the context name and type in the diagram frame can lead to clutter and is not always clear to non-SysML stakeholders (although that is the style used in the specification samples)

The Webel modelling style, naming conventions, and Best Practices for SysML are more consistent than most SysML spec diagrams. When following Webel courses please DO NOT use the spec sample diagrams (which serve a different purpose) as visual references!

Webel: SysMLv1: Highly recommend creating a "focus" Block Definition Diagram (BDD) for each main Block with expanded feature details and relationships to at least nearest neighbours

SysML: MagicDraw/Cameo: Diagram Style: Recommend DO NOT use shadows or gradient fill adornments on diagrams! [TIP OFTEN IGNORED]

Webel's Best Practice policy notes for MBSE with SysMLv1/UML2 and the MagicDraw/Cameo tools

Keywords

Keywords

Looking for the Webel Best Practices for the newer SysMLv2?

Subscribe to Webel Best Practice

We are Australia's Systems Modeling Language (SysML^®) and Model-Based Systems Engineering (MBSE) specialists!

Catch our SysMLv2 Workshop Course deal 20% off all bookings
fully pre-paid by 31st Oct 2026!

Learn at your own pace with our SysMLv2 Online self-study course with Quizzes and worked exercises!

SysMLv1 slide set PDFs now available for purchase!

Home of the Webel Parsing Analysis recipe for Model-Based Systems Engineering with SysML^®

Visit our Client showcase